GraphQL – Filter orders by return_status

Technical Q&A
,
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