Skip to main content

Return

Requires one of the read_returns or read_marketplace_returns access scopes.

Subscribe to field-level change events 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 the parent's webhook. 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.

Note

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

[events]
api_version = "unstable"

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

shopify.app.toml

Return line item quantities

[events]
api_version = "unstable"

[[events.subscription]]
handle = "return_line_quantities"

topic = "Return"
actions = ["update"]
triggers = [
"return.returnLineItems.refundableQuantity",
"return.returnLineItems.refundedQuantity",
"return.returnLineItems.unprocessedQuantity",
]

uri = "https://your-app.com/events"

query = """
query return_line_quantities($returnId: ID!) {
return(id: $returnId) {
id
status
returnLineItems(first: 50) {
nodes {
id
refundableQuantity
refundedQuantity
unprocessedQuantity
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
"""

Anchor to Supported triggersSupported triggers

Field-level triggers for Return events.

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.

You can include multiple triggers in a subscription. Each delivery carries a unique composite key in the shopify-webhook-id header. Use this value to detect and ignore duplicate deliveries.

Custom queries aren't limited to Return. You can query other GraphQL Admin API objects as needed for your use case.

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