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 →
returns/approve
documented from Shopify docs (example)
returns/approve Return approved and moved to OPEN
Identified by x-shopify-topic header
Resource returns
{
"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
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 123134564567890 |
status | string | open |
Full schema: 26 fields.
From Shopify docs
-
Content type
application/json
returns/cancel
documented from Shopify docs (example)
returns/cancel Return is canceled
Identified by x-shopify-topic header
Resource returns
{
"id": 123134564567890,
"admin_graphql_api_id": "gid://shopify/Return/123134564567890",
"order_id": 4783296544821,
"status": "canceled"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 123134564567890 |
status | string | canceled |
Full schema: 4 fields.
From Shopify docs
-
Content type
application/json
returns/close
documented from Shopify docs (example)
returns/close Return is closed
Identified by x-shopify-topic header
Resource returns
{
"id": 123134564567890,
"admin_graphql_api_id": "gid://shopify/Return/123134564567890",
"order_id": 4783296544821,
"status": "closed"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 123134564567890 |
status | string | closed |
Full schema: 4 fields.
From Shopify docs
-
Content type
application/json
returns/decline
documented from Shopify docs (example)
returns/decline Return declined and moved to DECLINED
Identified by x-shopify-topic header
Resource returns
{
"id": 123134564567890,
"admin_graphql_api_id": "gid://shopify/Return/123134564567890",
"status": "declined",
"decline": { … }
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 123134564567890 |
status | string | declined |
Full schema: 9 fields.
From Shopify docs
-
Content type
application/json
returns/process
documented No payload yet
returns/process Return is processed
Identified by x-shopify-topic header
Resource returns
No payload yet.
returns/reopen
documented from Shopify docs (example)
returns/reopen Closed return is reopened
Identified by x-shopify-topic header
Resource returns
{
"id": 123134564567890,
"admin_graphql_api_id": "gid://shopify/Return/123134564567890",
"order_id": 4783296544821,
"status": "open"
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 123134564567890 |
status | string | open |
Full schema: 4 fields.
From Shopify docs
-
Content type
application/json
returns/request
documented from Shopify docs (example)
returns/request Return requested, with status REQUESTED
Identified by x-shopify-topic header
Resource returns
{
"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
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 123134564567890 |
status | string | requested |
Full schema: 12 fields.
From Shopify docs
-
Content type
application/json
returns/update
documented from Shopify docs (example)
returns/update Return details change
Identified by x-shopify-topic header
Resource returns
{
"admin_graphql_api_id": "gid://shopify/Return/123134564567890",
"return_line_items": { … },
"restocking_fees": { … },
"return_shipping_fees": { … }
} From Shopify docs
-
Content type
application/json
reverse_deliveries/attach_deliverable
documented from Shopify docs (example)
reverse_deliveries/attach_deliverable Deliverable attached to a reverse delivery
Identified by x-shopify-topic header
Resource returns
{
"id": 9080907654321,
"admin_graphql_api_id": "gid://shopify/ReverseDelivery/9080907654321",
"return": { … },
"shipping_deliverable": { … }
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 9080907654321 |
Full schema: 13 fields.
From Shopify docs
-
Content type
application/json
reverse_fulfillment_orders/dispose
documented from Shopify docs (example)
reverse_fulfillment_orders/dispose Disposition made on a reverse fulfillment order
Identified by x-shopify-topic header
Resource returns
{
"id": 11111111,
"admin_graphql_api_id": "gid://shopify/ReverseFulfillmentOrder/11111111",
"dispositions": [ … ],
"total_dispositions": 2
} Key fields
| Field | Type | Example |
|---|---|---|
id | integer | 11111111 |
Full schema: 14 fields.
From Shopify docs
-
Content type
application/json
Route Shopify events by type.
Event Gateway receives every Shopify delivery and filters and routes it by event type, so each service gets only the events it handles.