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)

Return approved and moved to OPEN

Identified by x-shopify-topic header Resource returns

shopify-returns-approve.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
}

Key fields

Field Type Example
id integer 123134564567890
status string open

Full schema: 26 fields.

From Shopify docs

  • Content type application/json

Send example to Inspect → View as JSON

returns/cancel

documented from Shopify docs (example)

Return is canceled

Identified by x-shopify-topic header Resource returns

shopify-returns-cancel.json
{
  "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

Send example to Inspect → View as JSON

returns/close

documented from Shopify docs (example)

Return is closed

Identified by x-shopify-topic header Resource returns

shopify-returns-close.json
{
  "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

Send example to Inspect → View as JSON

returns/decline

documented from Shopify docs (example)

Return declined and moved to DECLINED

Identified by x-shopify-topic header Resource returns

shopify-returns-decline.json
{
  "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

Send example to Inspect → View as JSON

returns/process

documented No payload yet

Return is processed

Identified by x-shopify-topic header Resource returns

No payload yet.

Help fill this in → View as JSON

returns/reopen

documented from Shopify docs (example)

Closed return is reopened

Identified by x-shopify-topic header Resource returns

shopify-returns-reopen.json
{
  "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

Send example to Inspect → View as JSON

returns/request

documented from Shopify docs (example)

Return requested, with status REQUESTED

Identified by x-shopify-topic header Resource returns

shopify-returns-request.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
}

Key fields

Field Type Example
id integer 123134564567890
status string requested

Full schema: 12 fields.

From Shopify docs

  • Content type application/json

Send example to Inspect → View as JSON

returns/update

documented from Shopify docs (example)

Return details change

Identified by x-shopify-topic header Resource returns

shopify-returns-update.json
{
  "admin_graphql_api_id": "gid://shopify/Return/123134564567890",
  "return_line_items": { … },
  "restocking_fees": { … },
  "return_shipping_fees": { … }
}

From Shopify docs

  • Content type application/json

Send example to Inspect → View as JSON

reverse_deliveries/attach_deliverable

documented from Shopify docs (example)

Deliverable attached to a reverse delivery

Identified by x-shopify-topic header Resource returns

shopify-reverse-deliveries-attach-deliverable.json
{
  "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

Send example to Inspect → View as JSON

reverse_fulfillment_orders/dispose

documented from Shopify docs (example)

Disposition made on a reverse fulfillment order

Identified by x-shopify-topic header Resource returns

shopify-reverse-fulfillment-orders-dispose.json
{
  "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

Send example to Inspect → View as 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.

Not affiliated with Shopify. Facts are compiled from public sources and linked inline.