GraphQL – Filter orders by return_status

Technical Q&A
,

Topic summary

A developer is experiencing inconsistent behavior when filtering Shopify orders by return_status using GraphQL.

The Issue:

  • Querying orders without filters correctly returns an order with returnStatus: "IN_PROGRESS" and a return with status: "OPEN"
  • Adding the filter query: "return_status:open" (as documented) returns empty results
  • Using query: "return_status:in_progress" returns the correct order but triggers a warning: “Input in_progress is not an accepted value”

Key Confusion Points:

  • Documentation indicates return_status:open is a valid filter, yet it produces no results
  • The warning message suggests in_progress isn’t valid, despite it being the actual returnStatus value and successfully retrieving the order
  • There’s a mismatch between the order’s returnStatus field (“IN_PROGRESS”) and the individual return’s status field (“OPEN”)

Current Status:
The discussion remains unresolved. The developer questions whether they’re missing something or if the documentation/API behavior is incorrect. No responses or solutions have been provided yet.

Summarized with AI on November 4. AI used: claude-sonnet-4-5-20250929.
1

Hey there,

I am a bit confused by the GraphQL API Behaviour / Documentation regarding an order query with filter for return_status.

If I query for the following:

query GetOpenReturns {
  orders(first: 15) {
    edges {
      node {
        id
        name
        returnStatus
        returns(first: 10) {
          nodes {
            id
            status
          }
        }
      }
    }
  }
}

there is one order in the result with the Status of the return being “OPEN”

{
          "node": {
            "id": "gid://shopify/Order/5930994860310",
            "name": "#1013",
            "returnStatus": "IN_PROGRESS",
            "returns": {
              "nodes": [
                {
                  "id": "gid://shopify/Return/9808445718",
                  "status": "OPEN"
                }
              ]
            }
          }
        },

However, if I now filter by “return_status:open” (as shown here in the documentation, should be a valid query https://shopify.dev/docs/api/admin-graphql/2024-10/queries/orders)

query GetOpenReturns {
  orders(first: 15, query: "return_status:open") {
    edges {
      node {
        id
        name
        returnStatus
        returns(first: 10) {
          nodes {
            id
            status
          }
        }
      }
    }
  }
}

the API response is empty

{
  "data": {
    "orders": {
      "edges": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 37,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 20000,
        "currentlyAvailable": 19998,
        "restoreRate": 1000
      }
    },
    "search": [
      {
        "path": [
          "orders"
        ],
        "query": "return_status:open",
        "parsed": {
          "field": "return_status",
          "match_all": "open"
        }
      }
    ]
  }
}

If I filter for “return_status:in_progress” (https://shopify.dev/docs/api/admin-graphql/2024-10/enums/OrderReturnStatus)

query GetOpenReturns {
  orders(first: 15, query: "return_status:in_progress") {
    edges {
      node {
        id
        name
        returnStatus
        returns(first: 10) {
          nodes {
            id
            status
          }
        }
      }
    }
  }
}

I get the following result:

{
  "data": {
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/5930994860310",
            "name": "#1013",
            "returnStatus": "IN_PROGRESS",
            "returns": {
              "nodes": [
                {
                  "id": "gid://shopify/Return/9808445718",
                  "status": "OPEN"
                }
              ]
            }
          }
        }
      ]
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 37,
      "actualQueryCost": 6,
      "throttleStatus": {
        "maximumAvailable": 20000,
        "currentlyAvailable": 19994,
        "restoreRate": 1000
      }
    },
    "search": [
      {
        "path": [
          "orders"
        ],
        "query": "return_status:in_progress",
        "parsed": {
          "field": "return_status",
          "match_all": "in_progress"
        },
        "warnings": [
          {
            "field": "return_status",
            "message": "Input `in_progress` is not an accepted value."
          }
        ]
      }
    ]
  }
}

What I am wondering now is, that this response displays the warning “Input in_progress is not an accepted value.” but it displays the correct order.

So either way, the Documentation saying “return_status:open” is a valid filter or the warning “Input in_progress is not an accepted value.” is wrong and highly confusing and it took me some time to retreive the open orders.

Maybe I’m missing something important or is the Documentation not correct in this point?

Thanks and best wishes

Tim