Solved

Shopify Admin Graphql API Order Search Query Syntax

gilg
Shopify Partner
31 6 6

Is there any page that lists what the search parameters mean and what the valid values would be?

 

I read the search syntax page @ https://help.shopify.com/en/api/getting-started/search-syntax but that's more for general syntax than specific parameters such as risk_level or fraud_protection_level

 

For some of them I can guess or retrieve valid values from the REST api docs. For the others like channel_id or location_id or sales_channel, I don't really know what it's expecting. Any docs I'm overlooking?

 

Supported filter parameters (https://help.shopify.com/en/api/graphql-admin-api/reference/queryroot😞

  • cart_token
  • channel_id
  • chargeback_status
  • checkout_token
  • created_at
  • credit_card_last4
  • customer_id
  • discount_code
  • email
  • financial_status
  • fraud_protection_level
  • fulfillment_status
  • location_id
  • processed_at
  • reference_location_id
  • risk_level
  • sales_channel
  • source_name
  • status
  • tag
  • test
  • updated_at
I make Checkout Promotions on the app store. Native pre & post purchase upsells - used by over 1,800 merchants.
Accepted Solution (1)

Zameer
Shopify Staff
297 31 90

This is an accepted solution.

Hey Gil,

 

This information is definitely available in our public GraphQL docs, it's just tied to the specific resource you're querying.

 

For example, the list of filter parameters which you provided are all associated with the Orders QueryRoot. To find the acceptable values of each parameter, you would have to navigate to the Order object itself. This is all hyperlinked in the docs as QueryRoot -> QueryRoot.Orders -> OrderConnection -> OrderEdge -> Order (identical to what the structure of your GraphQL query would look like).

 

In the Order object docs you will see a list of all the supported fields. The supported filter parameters will all be present in this list of fields, and the possible values for each filter parameter will be documented when you select the field you're interested in. 

 

For example, for the `risk_level` filter parameter, there is a corresponding `riskLevel` field on the Order object of type OrderRiskLevel, the documentation for this type shows that the possible values are HIGH, MEDIUM and LOW. Following similar steps for the other filter parameters such as `financial_status` will provide you with its acceptable values as well.

 

Hope this helps!

To learn more visit the Shopify Help Center or the Community Blog.

View solution in original post

Replies 13 (13)

Zameer
Shopify Staff
297 31 90

This is an accepted solution.

Hey Gil,

 

This information is definitely available in our public GraphQL docs, it's just tied to the specific resource you're querying.

 

For example, the list of filter parameters which you provided are all associated with the Orders QueryRoot. To find the acceptable values of each parameter, you would have to navigate to the Order object itself. This is all hyperlinked in the docs as QueryRoot -> QueryRoot.Orders -> OrderConnection -> OrderEdge -> Order (identical to what the structure of your GraphQL query would look like).

 

In the Order object docs you will see a list of all the supported fields. The supported filter parameters will all be present in this list of fields, and the possible values for each filter parameter will be documented when you select the field you're interested in. 

 

For example, for the `risk_level` filter parameter, there is a corresponding `riskLevel` field on the Order object of type OrderRiskLevel, the documentation for this type shows that the possible values are HIGH, MEDIUM and LOW. Following similar steps for the other filter parameters such as `financial_status` will provide you with its acceptable values as well.

 

Hope this helps!

To learn more visit the Shopify Help Center or the Community Blog.

MozzoERP
Shopify Partner
84 4 20

Hi @Zameer , has this changed?

 


@Zameer wrote:

In the Order object docs you will see a list of all the supported fields. The supported filter parameters will all be present in this list of fields, and the possible values for each filter parameter will be documented when you select the field you're interested in. 

If I navigate to the Order object, I do not see filter parameters there. If you go to the QueryRoot reference, there is a list of "Supported filter parameters", but they don't list the available options for each parameter...i.e. fulfillment_status is a `filter parameter`, but what are the available filter values for that parameter?

 

So the net of my question is: where can you find the full list of filter parameters along with their valid values for each object?

Chad Richardson
Mozzo Software - Modular Software that grows with you from solopreneur to a 200 person mega team. Why keep outgrowing your Shopify Apps? Start with us, and just use the modules you need, then add more as you grow. http://MozzoERP.com
johanson
Tourist
10 0 13

The fact that the graphQL documentation does not provide accurate information is a problem.

 

For instance, if you want to use graphQL to return orders, filtered by financial_status as described here: https://help.shopify.com/en/api/graphql-admin-api/reference/queryroot

The biggest challenge is this is not a returnable element in the query.  The query returns the element called "displayFinancialStatus".

Then the values for this filter have to be lowercase such as "paid" or "authorized".

 

Another great example is the filterable field "status", again listed in the first link above.  There is NOTHING that matches this if you use the same approach as above.  So what is "status"?  Who knows.

 

Finally, things are just wrong in the docs.  Again, the first link references a filter field "tag".  Its actually "tags".

 

GraphQL is not the most straightforward API, but having incorrect and or missing documentation makes it a real pita.

heartwhite
Visitor
3 0 0

is it possible to query orders between dates?

is there any technique for that?

etbh
Visitor
1 0 0

For instance, if you want to use graphQL to return orders, filtered by financial_status as described here: https://help.shopify.com/en/api/graphql-admin-api/reference/queryroot

The biggest challenge is this is not a returnable element in the query.  The query returns the element called "displayFinancialStatus".

Then the values for this filter have to be lowercase such as "paid" or "authorized".

Another great example is the filterable field "status", again listed in the first link above.  There is NOTHING that matches this if you use the same approach as above.  So what is "status"?  Who knows.

This is what's been driving me crazy for the past hours.

I eventually figured out that the REST documentation actually covers all of that : https://shopify.dev/docs/admin-api/rest/reference/orders/order?api%5Bversion%5D=2020-10#index-2020-1...

 

mt686
Shopify Partner
52 9 17

Thank You! Was stuck on this for a sec, as the Shopify GraphiQL App was returning the right data, but running it on postman/my app was not. Turns out the GQL app will take 'tag' as a valid query filter, but requesting anywhere else it needs to be the plural 'tags'. A bit frustrating. 

theptrk
Tourist
9 1 5

Thanks for the help @Zameer .

I'm still finding this advice doesn't work for Orders.

I want to filter by orders that are not "FULFILLED".

In this example https://shopify.dev/concepts/graphql/queries, filtering by "FULFILLED" orders uses "shipped" 

 

query {
  orders(first:2, query:"fulfillment_status:shipped") {

 

but if you look at the docs for Order in QueryRoot -> QueryRoot.Orders -> OrderConnection -> OrderEdge -> Order 

"fulfillment_status" does not exist, only "displayFulfillmentStatus" exists and there is no option for "shipped" in that field.

However, "fulfillment status" does exist in the REST API docs and the stated valid values are 

- fulfilled

- null

- partial

- restocked

docs: https://shopify.dev/docs/admin-api/rest/reference/orders/order

but this query returns all orders

 

    orders(first: 10, query: "fulfillment_status:null") {
      edges {

 

  How do you filter by orders that are not "fulfilled"?

MozzoERP
Shopify Partner
84 4 20

Try this: 

orders(query: "fulfillment_status:unfulfilled AND financial_status:paid", first:50, reverse:true) 
Chad Richardson
Mozzo Software - Modular Software that grows with you from solopreneur to a 200 person mega team. Why keep outgrowing your Shopify Apps? Start with us, and just use the modules you need, then add more as you grow. http://MozzoERP.com
theptrk
Tourist
9 1 5

Thanks @MozzoERP , "unfulfilled" still didn't work for me, but filtering by "unshipped" did.

I could not find any documentation for this but it was answered here: https://community.shopify.com/c/Shopify-APIs-SDKs/How-can-I-get-all-orders-by-admin-orders-json-filt...

dylanpierce
Shopify Partner
210 3 94

Unfortunately I have to dog pile on this issue as well.

Repeating the same issues described above. The Order connection does not specify the available options for each filter in the search. If you like guessing games, you're in luck!

For the rest of us, we're struggling to find the appropriate labels for a given filter because they don't match the exact values in the fields of the GraphQL Order Object.

For example, searching on order_risks, the in Order GraphQL definition the available statuses are LOW, MEDIUM, and HIGH.

However, the filter parameter `order_risks` only accepts medium or high. Don't pass low or the whole query breaks and returns empty results.

In addition, the base query filter doesn't specify if you need to exactly pass the term `query` or not. It's a bit confusing. Do I need to do:

`query=Dylan AND risk_level=high` or does one need to do `Dylan AND risk_level=high` being passed to the GraphQL client.

Founder of Real ID - Verify your customer's real IDs easily & securely with modern A.I.

Want to see it in action? Check out our demo store.

ktbishop
Shopify Partner
20 1 3

I hate to do it, but I have to dog pile on this too.

 

Not providing meaningful documentation about request parameters, their possible values, or even what attributes they pertain to is pretty awful. You're basically leaving developers to make guesses about your API and hope that we guess correctly (lest we end up nuking our apps in production).

 

For example, the "reference_location_id" filter. What does that pertain to? After spending considerable time doing my own testing it SEEMS to scan the assigned location ids of all the FulfillmentOrders on an Order and returns the Order if any of those assigned location ids matches the given parameter. However, nothing in your API docs confirms any of this so it's all just speculation. 

Kyle B.
ShopifyDevSup
Shopify Staff
1299 210 451

Hey @ktbishop. I really appreciate you chiming in and sharing your thoughts. Your feedback is super valuable to us and I'm definitely going to relay this to our documentation team. 

Just a quick heads up for any other document issues you may encounter, you'll notice a little question at the bottom of all our docs asking, "Was this page helpful?" with a yes or no option. If you click on that, you'll get a chance to elaborate on your experience. This feedback goes straight to our documentation team and it's the prime spot to flag any unclear documents.
 

Now, let's dive into the specifics of your example,  the "reference_location_id" filter you're talking about, it's not confined to assigned locations. It actually refers to any instance of that ID on an order. So, for instance, it will also pull up orders linked to a physical location with that ID, regardless of the fulfillment orders being at different locations.
 

Hope this clears things up!

Kyle G. 

Developer Support @ Shopify
- Was this reply helpful? Click Like to let us know!
- Was your question answered? Mark it as an Accepted Solution
- To learn more visit Shopify.dev or the Shopify Web Design and Development Blog

ktbishop
Shopify Partner
20 1 3

Thanks for the quick response to this! I've used the "Was this page helpful?" a time or two but I haven't seen any updates yet. Hoping there is just a backlog of updates being worked on and that we'll see some of those improvements in the near future.

 

Thank you for clarifying the "reference_location_id" param!

Kyle B.