GraphQL returnCreate Mutation – “Return line item has an invalid quantity” but return is created in Admin

GraphQL Admin API Troubleshooting
1

Hi everyone,

I’m experiencing an issue with the GraphQL returnCreate mutation when creating a return via the Admin API.

Here is the mutation I’m sending:

{
  "query": "mutation ReturnCreate($returnInput: ReturnInput!) {
    returnCreate(returnInput: $returnInput) {
      return {
          id
          name
          status
          returnLineItems(first: 250) {
              nodes {
              ... on ReturnLineItem {
                  id
                  fulfillmentLineItem {
                      id
                      lineItem {
                          id
                          name
                          sku
                      }
                  }
              }
              customerNote
              returnReasonDefinition {
                 name
              }
              returnReasonNote
              quantity
              }
          }
      }
      userErrors {
        field
        message
      }
    }
  }",
  "variables": {
    "returnInput": {
      "orderId": "gid://shopify/Order/7406351745255",
      "requestedAt": "2026-02-26T22:08:01+01:00",
      "notifyCustomer": false,
      "returnLineItems": [
        {
          "quantity": 1,
          "returnReason": "SIZE_TOO_SMALL",
          "returnReasonNote": "Je veux la changer avec un autre article",
          "fulfillmentLineItemId": "gid://shopify/FulfillmentLineItem/14687449743591"
        }
      ]
    }
  }
}

And here is the response I receive:

{
  "data": [
    {
      "field": [
        "returnInput",
        "returnLineItems",
        "0",
        "quantity"
      ],
      "message": "Return line item has an invalid quantity."
    }
  ]
}

However, despite this error response, the return request is actually created successfully in the Shopify Admin back office.

So my questions are:

  • Why is the API returning "Return line item has an invalid quantity"?

  • Is this a known issue with the returnCreate mutation?

  • Could this be related to fulfillment quantities, partial fulfillments, or remaining returnable quantities?

  • Is the error possibly triggered by some internal validation but not blocking the creation?

The quantity I’m sending is 1, and the fulfillment line item definitely has a fulfillable quantity ≥ 1.

Has anyone experienced this inconsistent behavior?

Thanks in advance for your help.

1 Like
2

Hi @kais_msalmi,

It is certainly possible to receive this error due to partial fulfillments, unfulfilled line items, or fulfilled line items that have been refunded but not returned already.

It’s hard to say exactly why this occurred in your case without looking at the specific examples on our end, and to do so we would need you to reach out to our support team via the Shopify Help Center to ensure that the support interaction is fully authenticated to allow us to look into store specific information.

If you do reach to our Support Team to help look into this further, please be sure that you are logged into either a Staff account on the store in question, or a Partner account connected to the app making the API call for, full authentication. Additionally, please have the following information from the API call that experienced prepared when you reach out so we can help as efficiently as possible.

  • The full plain text HTTP Request, including URL, Body, and Headers (no access tokens)
  • The full plain text HTTP Response, including Body and Headers

(you’ve provided the HTTP Request and Response Bodies above, but we’ll need the Headers as well for full troubleshooting and to locate the calls in our internal logs)