Shopify Adds Origin and Destination IDs to Inventory Transfer Webhooks
Add origin.id and destination.id to your webhook handlers to track inventory movement without extra API calls.
Patch your webhook processing to read origin.id and destination.id when present; update inventoryTransferSetItems and inventoryTransferRemoveItems logic to match clarified behavior; test error handling for new descriptive messages.
Summary
Shopify has added origin.id and destination.id fields to all inventory transfer webhook payloads, using Location Global IDs such as gid://shopify/Location/123. These IDs allow developers to identify the source and destination of inventory movements without an extra API call. The new fields appear only for webhook subscriptions that use the unstable API version; earlier versions omit them entirely.
The article also clarifies the behavior of inventoryTransferSetItems and inventoryTransferRemoveItems. inventoryTransferSetItems is now described as an upsert that only affects the line items supplied, preserving existing items and replacing processableQuantity on READY_TO_SHIP or IN_PROGRESS transfers. inventoryTransferRemoveItems can be called on DRAFT or READY_TO_SHIP transfers, removing unallocated items or reducing quantity while preserving allocated portions, and returning reserved inventory to the origin on READY_TO_SHIP removals.
Error messages for inventory transfer mutations have been made more descriptive, such as READY_TO_SHIP_TRANSFER_REQUIRES_AT_LEAST_ONE_ITEM and ITEM_FULLY_SHIPPED, to help developers act without consulting docs. Existing error codes remain unchanged, so current error handling logic continues to work.
Key changes
- origin.id and destination.id added to all inventory transfer webhook payloads (Location Global IDs)
- New fields only present for webhook subscriptions using unstable API version; omitted in earlier versions
- inventoryTransferSetItems is an upsert affecting only supplied line items; processableQuantity replaced on READY_TO_SHIP/IN_PROGRESS transfers
- inventoryTransferRemoveItems can be called on DRAFT or READY_TO_SHIP; removes unallocated items or reduces quantity, preserving allocated portions
- Removing items on READY_TO_SHIP returns reserved quantity to available inventory at origin
- Passing empty transferLineItemIds to inventoryTransferRemoveItems is now a no‑op
- Error message READY_TO_SHIP_TRANSFER_REQUIRES_AT_LEAST_ONE_ITEM now explains cancellation requirement
- Error message ITEM_FULLY_SHIPPED clarifies allocation check rather than physical shipment