Skip to main content

Return

Requires one of the 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.

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. Calculated fields, derived fields, auto-updated timestamps, and cross-domain fields aren't available as triggers.

shopify.app.toml

[events]
api_version = "2026-10"

[[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
}
}
"""

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.

Anchor to list-of-topics-return.*
return.*

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 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

Anchor to list-of-topics-return.closedAt
return.closedAt

Fires when the closedAt 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 fields_changed.

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

Variables: returnId

Anchor to list-of-topics-return.decline
return.decline

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 fields_changed.

Additional information about the declined return.

Variables: returnId

Anchor to list-of-topics-return.exchangeLineItems
return.exchangeLineItems

Fires when the exchangeLineItems 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 fields_changed.

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

Variables: exchangeLineItemsId, returnId

Anchor to list-of-topics-return.requestApprovedAt
return.requestApprovedAt

Fires when the requestApprovedAt 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 fields_changed.

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

Variables: returnId

Anchor to list-of-topics-return.returnLineItems.*
return.returnLineItems.*

Fires when the returnLineItems field on the 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

Anchor to list-of-topics-return.returnLineItems.quantity
return.returnLineItems.quantity

Fires when the quantity field on the ReturnLineItemType 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 fields_changed.

The quantity field represents the quantity being returned.

Variables: returnId, returnLineItemsId

Anchor to list-of-topics-return.returnLineItems.refundableQuantity
return.returnLineItems.refundableQuantity

Fires when the refundableQuantity field on the ReturnLineItemType 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 fields_changed.

The refundableQuantity field represents the quantity that can be refunded.

Variables: returnId

Anchor to list-of-topics-return.returnLineItems.refundedQuantity
return.returnLineItems.refundedQuantity

Fires when the refundedQuantity field on the ReturnLineItemType 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 fields_changed.

The refundedQuantity field represents the quantity that was refunded.

Variables: returnId

Anchor to list-of-topics-return.returnLineItems.restockingFee.*
return.returnLineItems.restockingFee.*

Fires when the restockingFee field on the ReturnLineItem object changes.

return.returnLineItems.restockingFee.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under return.returnLineItems.restockingFee, 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 restockingFee field represents the restocking fee for the return line item.

Variables: returnId, returnLineItemsId

Anchor to list-of-topics-return.returnLineItems.restockingFee.amountSet.*
return.returnLineItems.restockingFee.amountSet.*

Fires when the amountSet field on the RestockingFee object changes.

return.returnLineItems.restockingFee.amountSet.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under return.returnLineItems.restockingFee.amountSet, 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 amountSet field represents the amount of the restocking fee, in shop and presentment currencies.

Variables: returnId, returnLineItemsId

Anchor to list-of-topics-return.returnLineItems.restockingFee.amountSet.presentmentMoney
return.returnLineItems.restockingFee.amountSet.presentmentMoney

Fires when the presentmentMoney field on the MoneyBag 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.

Amount in presentment currency.

Variables: returnId, returnLineItemsId

Anchor to list-of-topics-return.returnLineItems.restockingFee.amountSet.shopMoney
return.returnLineItems.restockingFee.amountSet.shopMoney

Fires when the shopMoney field on the MoneyBag 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.

Amount in shop currency.

Variables: returnId, returnLineItemsId

Anchor to list-of-topics-return.returnLineItems.restockingFee.percentage
return.returnLineItems.restockingFee.percentage

Fires when the percentage field on the RestockingFee 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 percentage field represents the value of the fee as a percentage.

Variables: returnId, returnLineItemsId

Anchor to list-of-topics-return.returnLineItems.unprocessedQuantity
return.returnLineItems.unprocessedQuantity

Fires when the unprocessedQuantity field on the ReturnLineItemType 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 fields_changed.

The unprocessedQuantity field represents the quantity that has't been processed.

Variables: returnId

Anchor to list-of-topics-return.returnShippingFees.*
return.returnShippingFees.*

Fires when the returnShippingFees field on the Return object changes.

return.returnShippingFees.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under return.returnShippingFees, 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 returnShippingFees field represents the return shipping fees for the return.

Variables: returnId, returnShippingFeesId

Anchor to list-of-topics-return.returnShippingFees.amountSet.*
return.returnShippingFees.amountSet.*

Fires when the amountSet field on the ReturnShippingFee object changes.

return.returnShippingFees.amountSet.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under return.returnShippingFees.amountSet, 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 amountSet field represents the amount of the return shipping fee, in shop and presentment currencies.

Variables: returnId, returnShippingFeesId

Anchor to list-of-topics-return.returnShippingFees.amountSet.presentmentMoney
return.returnShippingFees.amountSet.presentmentMoney

Fires when the presentmentMoney field on the MoneyBag 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.

Amount in presentment currency.

Variables: returnId, returnShippingFeesId

Anchor to list-of-topics-return.returnShippingFees.amountSet.shopMoney
return.returnShippingFees.amountSet.shopMoney

Fires when the shopMoney field on the MoneyBag 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.

Amount in shop currency.

Variables: returnId, returnShippingFeesId

Anchor to list-of-topics-return.reverseFulfillmentOrders.*
return.reverseFulfillmentOrders.*

Fires when the reverseFulfillmentOrders field on the Return object changes.

return.reverseFulfillmentOrders.* is a parent trigger. Subscribing with the "update" action receives events for all supported triggers under return.reverseFulfillmentOrders, 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 reverseFulfillmentOrders field represents the list of reverse fulfillment orders for the return.

Variables: returnId, reverseFulfillmentOrdersId

Anchor to list-of-topics-return.reverseFulfillmentOrders.lineItems
return.reverseFulfillmentOrders.lineItems

Fires when the lineItems field on the ReverseFulfillmentOrder 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 lineItems field represents the list of reverse fulfillment order line items for the reverse fulfillment order.

Variables: lineItemsId, returnId, reverseFulfillmentOrdersId

Anchor to list-of-topics-return.reverseFulfillmentOrders.status
return.reverseFulfillmentOrders.status

Fires when the status field on the ReverseFulfillmentOrder 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 reverse fulfillment order.

Variables: returnId, reverseFulfillmentOrdersId

Anchor to list-of-topics-return.status
return.status

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 fields_changed.

The status field represents the status of the return.

Variables: returnId

Was this page helpful?