New Return Reason Definitions API for Better Return Insights

You can now use the new ReturnReasonDefinition type to capture more granular, category-specific return reasons when managing returns. This replaces the previous ReturnReason enum with a richer data model that helps provide merchants with better insights in their return analytics, and more tailored return experiences for their buyers.

What's new

• A new ReturnReasonDefinition type with id, handle, and name fields. Use the stable handle for programmatic logic.
• The returnReasonDefinitions query retrieves the full library of available return reasons.
• A new suggestedReturnReasonDefinitions connection on LineItem provides return reasons tailored to each product's category.
• The returnCreate, returnRequest, and orderRequestReturn mutations now accept returnReasonDefinitionId in their line item inputs.
• Access returnReasonDefinition on ReturnLineItem and UnverifiedReturnLineItem types.

Deprecations

The returnReason field on input types and return line item types is deprecated. Use returnReasonDefinitionId for inputs and returnReasonDefinition for reading return data.

Migration

If your app creates returns, update your mutations to use returnReasonDefinitionId instead of returnReason. Query suggestedReturnReasonDefinitions on LineItem to get contextually relevant reasons for each product. For reading returns, update your queries to use returnReasonDefinition instead of returnReason.

These changes are available in API version 2026-01.