# Shopify returns webhook events

Shopify sends 10 returns events, including `returns/approve`, `returns/cancel` and `returns/close`. 9 have sample payloads. Every event here can also reach agents as an MCP event through Hookdeck: [MCP events](https://hookdeck.com/webhooks/shopify/mcp-events).

Agent skill: `npx skills add hookdeck/webhook-skills --skill shopify-webhooks` ([details](https://hookdeck.com/webhooks/shopify/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Shopify's official docs](https://shopify.dev/docs/apps/build/webhooks/delivery-structure).

[Overview](https://hookdeck.com/webhooks/shopify) · [Webhook events (230)](https://hookdeck.com/webhooks/shopify/events) · [MCP events](https://hookdeck.com/webhooks/shopify/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/shopify/verify) · [Production guide](https://hookdeck.com/webhooks/shopify/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/shopify/skill)

## returns/approve

Confidence: documented · Schema: from Shopify docs (example)

Return approved and moved to OPEN

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 123134564567890,
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "status": "open",
  "order": { … },
  "total_return_line_items": 2,
  "name": null,
  "return_line_items": [ … ],
  "return_shipping_fees": [ … ],
  "exchange_line_items": [ … ],
  "total_exchange_line_items": 1
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-approve.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `123134564567890` |
| `status` | string | `open` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-approve.json)

## returns/cancel

Confidence: documented · Schema: from Shopify docs (example)

Return is canceled

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 123134564567890,
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "order_id": 4783296544821,
  "status": "canceled"
}
```



| Key field | Type | Example |
|---|---|---|
| `id` | integer | `123134564567890` |
| `status` | string | `canceled` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-cancel.json)

## returns/close

Confidence: documented · Schema: from Shopify docs (example)

Return is closed

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 123134564567890,
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "order_id": 4783296544821,
  "status": "closed"
}
```



| Key field | Type | Example |
|---|---|---|
| `id` | integer | `123134564567890` |
| `status` | string | `closed` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-close.json)

## returns/decline

Confidence: documented · Schema: from Shopify docs (example)

Return declined and moved to DECLINED

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 123134564567890,
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "status": "declined",
  "decline": { … }
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-decline.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `123134564567890` |
| `status` | string | `declined` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-decline.json)

## returns/process

Confidence: documented · Schema: No payload yet

Return is processed

Identified by: x-shopify-topic header · Object: `returns`

No payload yet.

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-process.json)

## returns/reopen

Confidence: documented · Schema: from Shopify docs (example)

Closed return is reopened

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 123134564567890,
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "order_id": 4783296544821,
  "status": "open"
}
```



| Key field | Type | Example |
|---|---|---|
| `id` | integer | `123134564567890` |
| `status` | string | `open` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-reopen.json)

## returns/request

Confidence: documented · Schema: from Shopify docs (example)

Return requested, with status REQUESTED

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 123134564567890,
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "status": "requested",
  "order": { … },
  "total_return_line_items": 2,
  "name": null,
  "return_line_items": [ … ],
  "return_shipping_fees": [ … ],
  "exchange_line_items": [ … ],
  "total_exchange_line_items": 0
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-request.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `123134564567890` |
| `status` | string | `requested` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-request.json)

## returns/update

Confidence: documented · Schema: from Shopify docs (example)

Return details change

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "return_line_items": { … },
  "restocking_fees": { … },
  "return_shipping_fees": { … }
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-update.json)

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/returns-update.json)

## reverse_deliveries/attach_deliverable

Confidence: documented · Schema: from Shopify docs (example)

Deliverable attached to a reverse delivery

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 9080907654321,
  "admin_graphql_api_id": "gid://shopify/ReverseDelivery/9080907654321",
  "return": { … },
  "shipping_deliverable": { … }
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/reverse-deliveries-attach-deliverable.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `9080907654321` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/reverse-deliveries-attach-deliverable.json)

## reverse_fulfillment_orders/dispose

Confidence: documented · Schema: from Shopify docs (example)

Disposition made on a reverse fulfillment order

Identified by: x-shopify-topic header · Object: `returns`

```json
{
  "id": 11111111,
  "admin_graphql_api_id": "gid://shopify/ReverseFulfillmentOrder/11111111",
  "dispositions": [ … ],
  "total_dispositions": 2
}
```

Trimmed sample. Full payload: [View as JSON](https://hookdeck.com/webhooks/shopify/events/reverse-fulfillment-orders-dispose.json)

| Key field | Type | Example |
|---|---|---|
| `id` | integer | `11111111` |

From Shopify docs: content type `application/json`

[View as JSON](https://hookdeck.com/webhooks/shopify/events/reverse-fulfillment-orders-dispose.json)

---

Not affiliated with Shopify. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/shopify.json) · [Report a correction](https://hookdeck.com/contact)
