Return
read_returns or read_marketplace_returns access scopes.read_returns or read_marketplace_returns access scopes.:Supported actions: create, update, delete
Subscribe to field-level changes on the 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 a delivery on the parent topic. Fields that you can reconstruct from other triggers, auto-updated timestamps, and fields owned by another topic aren't separate triggers. A field can still be a trigger when Shopify calculates its value internally.
The refundableQuantity, refundedQuantity, and unprocessedQuantity triggers are Return-level invalidations. One or more line item values might have changed. These events include returnId, but don't include a specific ReturnLineItem ID. Include each line item's id and the connection's pageInfo in your payload query. If hasNextPage is true, then use returnId and endCursor in a follow-up GraphQL Admin API request to query the remaining line items. The examples in the trigger list show a minimal payload, so use the paginated query in the Return line item quantities example when you need complete state.
processableQuantity is intentionally not a trigger. Subscribe to return.returnLineItems.refundableQuantity and return.status instead, then re-query the Return and select processableQuantity to read the current value.
processableQuantity is intentionally not a trigger. Subscribe to return.returnLineItems.refundableQuantity and return.status instead, then re-query the Return and select processableQuantity to read the current value.
shopify.app.toml
shopify.app.toml
Return line item quantities
Anchor to Supported triggersSupported triggers
Field-level triggers for Return subscriptions.
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.
Subscriptions can include multiple triggers. Use the shopify-webhook-id header for deduplication when handling duplicate deliveries.
Custom queries aren't limited to Return. They can query the full GraphQL Admin API.
Fires when events involve the 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 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:
Fires when the field on the 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 .
The field represents the date and time when the return was closed.
Variables:
Fires when the decline field on the 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 .
Additional information about the declined return.
Variables:
Fires when the field on the 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 .
The field represents the exchange line items attached to the return.
Variables: ,
Fires when the field on the 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 .
The field represents the date and time when the return was approved.
Variables:
Fires when the field on the Return object changes.
is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under , 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 .
The field represents the return line items attached to the return.
Variables: ,
Fires when the quantity field on the interface 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 .
The quantity field represents the quantity being returned.
Variables: ,
Fires when the field on the interface 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 .
The field represents the quantity that can be refunded.
Variables:
Fires when the field on the object changes.
is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under , 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 .
The field represents the restocking fee for the return line item.
Variables: ,
Fires when the field on the object changes.
is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under , 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 .
The field represents the amount of the restocking fee, in shop and presentment currencies.
Variables: ,
Fires when the percentage field on the 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 .
The percentage field represents the value of the fee as a percentage.
Variables: ,
Fires when the field on the interface 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 .
The field represents the quantity that has't been processed.
Variables:
Fires when the field on the Return object changes.
is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under , 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 .
The field represents the return shipping fees for the return.
Variables: ,
Fires when the field on the object changes.
is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under , 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 .
The field represents the amount of the return shipping fee, in shop and presentment currencies.
Variables: ,
Fires when the field on the Return object changes.
is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under , 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 .
The field represents the list of reverse fulfillment orders for the return.
Variables: ,
Fires when the field on the 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 .
The field represents the list of reverse fulfillment order line items for the reverse fulfillment order.
Variables: , ,
Fires when the status field on the 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 .
The status field represents the status of the reverse fulfillment order.
Variables: ,
Fires when the status field on the 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 .
The status field represents the status of the return.
Variables: