Return
Requires access scope.
A standardized reason for returning an item.
- Shopify offers an expanded library of return reasons available to all merchants
- For each product, Shopify suggests a curated subset of reasons based on the product's category
- Suggested reasons aren't the only valid options. When creating a return via the API, you can use any reason from the full library.
Anchor to FieldsFields
- Anchor to deleteddeleted•Boolean!non-null
Whether the return reason has been removed from taxonomy.
Deleted reasons should not be presented to customers when creating new returns, but may still appear on existing returns that were created before the reason was deleted. This field enables graceful deprecation of return reasons without breaking historical data.
- Anchor to handlehandle•String!non-null
A unique, human-readable, stable identifier for the return reason.
Example values include "arrived-late", "comfort", "too-tight", "color-too-bright", and "quality". The handle remains consistent across API versions and localizations, making it suitable for programmatic use.
- •ID!non-null
A globally-unique ID.
- Anchor to namename•String!non-null
The localized, user-facing name of the return reason.
This field returns the reason name in the requested locale, automatically falling back to English if no translation is available. Use this field when displaying return reasons to customers or merchants.
Anchor to QueriesQueries
- •query
Returns the full library of available return reason definitions.
Use this query to retrieve the standardized return reasons available for creating returns. Filter by IDs or handles to get specific definitions.
Only non-deleted reasons should be shown to customers when creating new returns. Deleted reasons have been replaced with better alternatives and are no longer recommended. However, they remain valid options and may still appear on existing returns.
- •[ID!]
A list of return reason definition IDs to filter by.
- Anchor to handleshandles•[String!]
A list of return reason definition handles to filter by.
- Anchor to firstfirst•Int
The first
nelements from the paginated list.- Anchor to afterafter•String
The elements that come after the specified cursor.
- Anchor to lastlast•Int
The last
nelements from the paginated list.- Anchor to beforebefore•String
The elements that come before the specified cursor.
- Anchor to reversereverse•BooleanDefault:false
Reverse the order of the underlying list.
- Anchor to sortKeysort•Return
Key Reason Definition Sort Keys Default:ID Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.
- Anchor to queryquery•String
A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.
Arguments