---
title: >-
  New Return Reason Definitions API for Better Return Insights - Shopify
  developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/new-return-reason-definitions-api-for-better-return-insights
  md: >-
    https://shopify.dev/changelog/posts/new-return-reason-definitions-api-for-better-return-insights.md
metadata:
  effectiveApiVersion: 2026-01
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
    - displayName: Customer Account API
      handle: customer-account-graphql
    - displayName: Events & webhooks
      handle: webhook
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2025-12-11T19:31:28-05:00'
  postedAt: '2026-01-01T12:00:00-05:00'
  updatedAt: '2025-12-20T03:36:11-05:00'
  effectiveAt: '2026-01-01T12:00:00-05:00'
---

January 1, 2026

# New Return Reason Definitions API for Better Return Insights

DateJanuary 1, 2026

Version[2026-01](https://shopify.dev/changelog?api_version=2026-01)

FlagsUpdate

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)[Customer Account API](https://shopify.dev/changelog?api_type=customer-account-graphql)[Events & webhooks](https://shopify.dev/changelog?api_type=webhook)

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`](https://shopify.dev/docs/api/admin-graphql/2026-01/objects/ReturnReasonDefinition) type with `id`, `handle`, and `name` fields. Use the stable `handle` for programmatic logic.
* The [`returnReasonDefinitions`](https://shopify.dev/docs/api/admin-graphql/2026-01/queries/returnReasonDefinitions) query retrieves the full library of available return reasons.
* A new `suggestedReturnReasonDefinitions` connection on [`LineItem`](https://shopify.dev/docs/api/admin-graphql/2026-01/objects/LineItem#field-LineItem.fields.suggestedReturnReasonDefinitions) provides return reasons tailored to each product's category.
* The [`returnCreate`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/returnCreate), [`returnRequest`](https://shopify.dev/docs/api/admin-graphql/2026-01/mutations/returnRequest), and [`orderRequestReturn`](https://shopify.dev/docs/api/customer/2026-01/mutations/orderRequestReturn) mutations now accept `returnReasonDefinitionId` in their line item inputs.
* Access `returnReasonDefinition` on [`ReturnLineItem`](https://shopify.dev/docs/api/admin-graphql/2026-01/objects/ReturnLineItem) and [`UnverifiedReturnLineItem`](https://shopify.dev/docs/api/admin-graphql/2026-01/objects/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.