---
title: Return
description: Subscribe to field-level change events on the Return GraphQL Admin API object.
api_version: unstable
source_url:
  html: 'https://shopify.dev/docs/api/events/latest/return'
  md: 'https://shopify.dev/docs/api/events/latest/return.md'
api_name: events
---

# Return

**Requires one of the `read_returns` or `read_marketplace_returns` access scopes.:**

Subscribe to field-level change events on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) GraphQL Admin API object. A return represents a buyer's intent to ship one or more order items back to a merchant or third-party fulfillment location. Return webhooks fire when Shopify creates, deletes, or updates a return, including when an app uses `returnCreate` to create one or when supported fields and child return line items change.

Each topic corresponds to a commerce resource that can exist independently within its domain. Child entities that depend on a parent within the same domain don't have their own topic. Instead, changes to child entities trigger the parent's webhook. Calculated fields, derived fields, auto-updated timestamps, and cross-domain fields aren't available as triggers.

## shopify.app.toml

```toml
[events]
api_version = "unstable"


[[events.subscription]]
handle = "my_return_event"


topic = "Return"
actions = ["update"]
triggers = ["return.closedAt"]


uri = "https://your-app.com/events"


query = """
query return_event_payload($returnId: ID!) {
  return(id: $returnId) {
    id
    name
    status
    closedAt
  }
}
"""
```

***

## Supported triggers

Field-level triggers for `Return` events.

All triggers require one of the `read_returns` or `read_marketplace_returns` access scopes. Those triggers that require additional scopes are documented where relevant. Deprecated triggers are listed last.

You can include multiple triggers in a subscription. Each delivery carries a unique composite key in the `shopify-webhook-id` header. Use this value to detect and ignore duplicate deliveries.

Custom queries aren't limited to [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return). You can query other GraphQL Admin API objects as needed for your use case.

### return​.\*

Fires when events involve the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object, which represents the intent of a buyer to ship one or more items from an order back to a merchant or a third-party fulfillment location.

The `"create"` and `"delete"` actions are only relevant within the context of this parent topic. Use `fields_changed` to follow or replicate impacted data after a delete event. Define a custom query to retrieve specific fields from create events.

`return.*` is a parent trigger. Subscribing with the `"update"` action receives events for all supported triggers under `return`, including nested triggers. Use a more specific trigger to limit events to the fields you need.

**Variables:** `returnId`

### return​.closedAt

Fires when the [`closedAt`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return#field-Return.fields.closedAt) field on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `closedAt` field represents the date and time when the return was closed.

**Variables:** `returnId`

### return​.decline

Fires when the [`decline`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return#field-Return.fields.decline) field on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

Additional information about the declined return.

**Variables:** `returnId`

### return​.exchangeLineItems

Fires when the [`exchangeLineItems`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return#field-Return.fields.exchangeLineItems) field on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `exchangeLineItems` field represents the exchange line items attached to the return.

**Variables:** `exchangeLineItemsId`, `returnId`

### return​.requestApprovedAt

Fires when the [`requestApprovedAt`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return#field-Return.fields.requestApprovedAt) field on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `requestApprovedAt` field represents the date and time when the return was approved.

**Variables:** `returnId`

### return​.returnLineItems​.\*

Fires when the [`returnLineItems`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return#field-Return.fields.returnLineItems) field on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object changes.

`return.returnLineItems.*` is a parent trigger. Subscribing with the `"update"` action receives events for all supported triggers under `return.returnLineItems`, including nested triggers. Use a more specific trigger to limit events to the fields you need.

Include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `returnLineItems` field represents the return line items attached to the return.

**Variables:** `returnId`, `returnLineItemsId`

### return​.returnLineItems​.quantity

Fires when the [`quantity`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/ReturnLineItem#field-ReturnLineItem.fields.quantity) field on the [`ReturnLineItem`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/ReturnLineItem) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `quantity` field represents the quantity being returned.

**Variables:** `returnId`, `returnLineItemsId`

### return​.status

Fires when the [`status`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return#field-Return.fields.status) field on the [`Return`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/Return) object changes.

Subscribe to this trigger with the `"update"` action and include the field in a custom `query` to retrieve updated data from the payload. You can trace the field in subsequent requests using `fields_changed`.

The `status` field represents the status of the return.

**Variables:** `returnId`

### Examples

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["create","update","delete"]
  triggers = ["return.*"]

  uri = "https://your-app.com/events"

  query = """
  query return_details($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
    }
  }
  """
  ```

  ##### Payload (added)

  ```json
  {
    "topic": "Return",
    "action": "create",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE"
      }
    },
    "fields_changed": {
      "added": [
        "return[id: 'gid://shopify/Return/5632446657570']"
      ],
      "updated": [],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Payload (updated)

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "return[id: 'gid://shopify/Return/5632446657570'].closedAt"
      ],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Payload (removed)

  ```json
  {
    "topic": "Return",
    "action": "delete",
    "handle": "return-event",
    "data": {
      "return": null
    },
    "fields_changed": {
      "added": [],
      "updated": [],
      "removed": [
        "return[id: 'gid://shopify/Return/5632446657570']"
      ]
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update # or create, delete
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.closedAt"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
      closedAt
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "closedAt": "…"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "return[id: 'gid://shopify/Return/5632446657570'].closedAt"
      ],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.decline"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
      decline {
        __typename
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "decline": {
          "__typename": "ReturnDecline"
        }
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "return[id: 'gid://shopify/Return/5632446657570'].decline"
      ],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.exchangeLineItems"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
      exchangeLineItems(first: 10) {
        nodes {
          id
        }
      }
    }
  }
  """
  ```

  ##### Payload (added)

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "exchangeLineItems": {
          "nodes": [
            {
              "id": "gid://shopify/ExchangeLineItem/7291118221173"
            }
          ]
        }
      }
    },
    "fields_changed": {
      "added": [
        "return[id: 'gid://shopify/Return/5632446657570'].exchangeLineItems[id: 'gid://shopify/ExchangeLineItem/7291118221173']"
      ],
      "updated": [],
      "removed": []
    },
    "query_variables": {
      "exchangeLineItemsId": "gid://shopify/ExchangeLineItem/7291118221173",
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Payload (removed)

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "exchangeLineItems": {
          "nodes": [
            {
              "id": "gid://shopify/ExchangeLineItem/111"
            }
          ]
        }
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [],
      "removed": [
        "return[id: 'gid://shopify/Return/5632446657570'].exchangeLineItems[id: 'gid://shopify/ExchangeLineItem/7291118221173']"
      ]
    },
    "query_variables": {
      "exchangeLineItemsId": "gid://shopify/ExchangeLineItem/7291118221173",
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.requestApprovedAt"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
      requestApprovedAt
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "requestApprovedAt": "…"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "return[id: 'gid://shopify/Return/5632446657570'].requestApprovedAt"
      ],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.returnLineItems.*"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
      returnLineItems(first: 10) {
        nodes {
          id
        }
      }
    }
  }
  """
  ```

  ##### Payload (added)

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "returnLineItems": {
          "nodes": [
            {
              "id": "gid://shopify/ReturnLineItem/6818717966715"
            }
          ]
        }
      }
    },
    "fields_changed": {
      "added": [
        "return[id: 'gid://shopify/Return/5632446657570'].returnLineItems[id: 'gid://shopify/ReturnLineItem/6818717966715']"
      ],
      "updated": [],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570",
      "returnLineItemsId": "gid://shopify/ReturnLineItem/6818717966715"
    }
  }
  ```

  ##### Payload (removed)

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "returnLineItems": {
          "nodes": [
            {
              "id": "gid://shopify/ReturnLineItem/111"
            }
          ]
        }
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [],
      "removed": [
        "return[id: 'gid://shopify/Return/5632446657570'].returnLineItems[id: 'gid://shopify/ReturnLineItem/6818717966715']"
      ]
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570",
      "returnLineItemsId": "gid://shopify/ReturnLineItem/6818717966715"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.returnLineItems.quantity"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
      returnLineItems(first: 10) {
        nodes {
          quantity
        }
      }
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE",
        "returnLineItems": {
          "nodes": [
            {
              "quantity": "…"
            }
          ]
        }
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "return[id: 'gid://shopify/Return/5632446657570'].returnLineItems[id: 'gid://shopify/ReturnLineItem/6818717966715'].quantity"
      ],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570",
      "returnLineItemsId": "gid://shopify/ReturnLineItem/6818717966715"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

* #### Subscribe via app configuration

  ##### shopify.app.toml

  ```toml
  [events]
  api_version = "unstable"

  [[events.subscription]]
  handle = "return-event"

  topic = "Return"
  actions = ["update"]
  triggers = ["return.status"]

  uri = "https://your-app.com/events"

  query = """
  query return_event_payload($returnId: ID!) {
    return(id: $returnId) {
      id
      name
      status
    }
  }
  """
  ```

  ##### Payload

  ```json
  {
    "topic": "Return",
    "action": "update",
    "handle": "return-event",
    "data": {
      "return": {
        "id": "gid://shopify/Return/5632446657570",
        "name": "Example return",
        "status": "ACTIVE"
      }
    },
    "fields_changed": {
      "added": [],
      "updated": [
        "return[id: 'gid://shopify/Return/5632446657570'].status"
      ],
      "removed": []
    },
    "query_variables": {
      "returnId": "gid://shopify/Return/5632446657570"
    }
  }
  ```

  ##### Headers

  ```bash
  shopify-action: update
  shopify-api-version: unstable
  shopify-handle: return-event
  shopify-hmac-sha256: 61lWIGuA2nXdHRjhMU/+EDw2y3Eg0mPKJ+RhR7dKKIM=
  shopify-shop-domain: your-shop.myshopify.com
  shopify-topic: Return
  shopify-triggered-at: 2026-03-23T16:24:35.267Z
  shopify-webhook-id: 7613956a-18a5-332d-b71e-e164bbcacdba
  ```

***