---
title: returnReasonDefinitions - GraphQL Admin
description: >-
  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.
api_version: 2026-01
api_name: admin
type: query
api_type: graphql
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-graphql/latest/queries/returnReasonDefinitions
  md: >-
    https://shopify.dev/docs/api/admin-graphql/latest/queries/returnReasonDefinitions.md
---

# return​Reason​Definitions

query

Requires `read_returns` access scope.

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.

## ReturnReasonDefinitionConnection arguments

[ReturnReasonDefinitionConnection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/ReturnReasonDefinitionConnection)

* after
* before
* first
* handles
* ids
* last
* query
* reverse
* sortKey

***

## Possible returns

* edges
* nodes
* pageInfo

***

## Examples

* ### Retrieve available return reason definitions

  #### Description

  Retrieve the list of return reason definitions available for creating returns. Return reason definitions provide standardized, localized reasons for returns. Use the \`id\` field when creating returns, and the \`name\` field to display the reason to customers.

  #### Query

  ```graphql
  query {
    returnReasonDefinitions(first: 10) {
      edges {
        node {
          id
          handle
          name
          deleted
        }
      }
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "query { returnReasonDefinitions(first: 10) { edges { node { id handle name deleted } } } }"
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    query {
      returnReasonDefinitions(first: 10) {
        edges {
          node {
            id
            handle
            name
            deleted
          }
        }
      }
    }`,
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    query {
      returnReasonDefinitions(first: 10) {
        edges {
          node {
            id
            handle
            name
            deleted
          }
        }
      }
    }
  QUERY

  response = client.query(query: query)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: `query {
      returnReasonDefinitions(first: 10) {
        edges {
          node {
            id
            handle
            name
            deleted
          }
        }
      }
    }`,
  });
  ```

  #### Response

  ```json
  {
    "returnReasonDefinitions": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/27368211",
            "handle": "damaged",
            "name": "Damaged",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/61598531",
            "handle": "not_as_described",
            "name": "Not as Described",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/118463786",
            "handle": "unwanted_2",
            "name": "Unwanted",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/148612955",
            "handle": "too-big",
            "name": "Too Big",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/305697940",
            "handle": "defective",
            "name": "Defective",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/551551176",
            "handle": "other-reason",
            "name": "Other",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/640710815",
            "handle": "too-small",
            "name": "Too Small",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/712232956",
            "handle": "style",
            "name": "Style",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/845857515",
            "handle": "too-late",
            "name": "Too Late",
            "deleted": false
          }
        },
        {
          "node": {
            "id": "gid://shopify/ReturnReasonDefinition/955827578",
            "handle": "defective_2",
            "name": "Defective",
            "deleted": false
          }
        }
      ]
    }
  }
  ```