Inventory transfer webhooks include origin and destination location IDs, and mutation documentation clarified

Inventory transfer webhooks: new origin and destination fields

Payloads for the following webhook topics now include the source and destination location of the transfer as Location Global IDs:

• inventory_transfers/add_items
• inventory_transfers/update_item_quantities
• inventory_transfers/remove_items
• inventory_transfers/ready_to_ship
• inventory_transfers/cancel
• inventory_transfers/complete

Each payload now includes:

• origin.id: For example, gid://shopify/Location/123
• **destination.id **: For example, gid://shopify/Location/456

You can use these IDs to identify where inventory is moving without making an additional API call to fetch the transfer.

The new fields are scoped to subscriptions whose webhook API version includes this change. The new functionality is available now on the unstable API version and will be in the upcoming public API release 2026-07. See the Inventory transfer webhook reference for details.

If your subscription is on an earlier version, or the transfer's source or destination is not a location (for example, a supplier-fulfilled transfer), the keys are omitted from the payload entirely rather than returned as null.

Clarified documentation for inventoryTransferSetItems

We've updated the description on inventoryTransferSetItems to better describe how it actually behaves. The behavior itself hasn't changed.

• inventoryTransferSetItems sets the quantity for each line item you pass, either adding it if it's not already on the transfer or updating it if it is. Line items you don't pass are unchanged. Each inventoryItemId may appear at most once per call.
• On a READY_TO_SHIP or IN_PROGRESS transfer, the quantity you pass replaces only the processableQuantity; already-shipped or picked quantity is preserved, and the resulting total is the preserved portion plus the provided quantity.
• quantity: 0 is only valid on DRAFT transfers, where it leaves a zero-quantity line item on the transfer. To remove a line item, use inventoryTransferRemoveItems. On READY_TO_SHIP or IN_PROGRESS transfers, 0 returns an INVALID_QUANTITY error.

Clarified documentation for inventoryTransferRemoveItems

We've also updated the description on inventoryTransferRemoveItems to better describe its behavior:

• The mutation can be called on transfers in DRAFT or READY_TO_SHIP status.
• You can remove items from In Transit shipments (using InventoryShipmentRemoveItem) and then remove it from the Transfer if the quantity has been placed on a shipment.
• For each line item you reference, if its full quantity is still unallocated to a shipment, then the line item is removed. Otherwise, the line item remains on the transfer with its quantity reduced to the allocated portion. Quantity allocated to a shipment, such as whether the shipment is still a draft, in transit, or already received, is preserved.
• On READY_TO_SHIP transfers, removing items returns the affected reserved quantity to available inventory at the origin location.
• Passing an omitted or empty transferLineItemIds is now treated as a no-op and returns the transfer unchanged.
• To change the quantity of a line item without removing it, use inventoryTransferSetItems.

Clearer error messages on inventory transfer mutations

Several user errors returned by the inventory transfer mutations now have more descriptive messages so that you can act on them without consulting additional docs:

• READY_TO_SHIP_TRANSFER_REQUIRES_AT_LEAST_ONE_ITEM now explains that you can't remove every line item from a READY_TO_SHIP transfer and that, to empty one, you should cancel it instead.
• ALL_QUANTITY_SHIPPED now clarifies that the check fires when the full quantity of the item is allocated to one or more shipments (including draft shipments where the item has been picked), and that the error name refers to the underlying allocation check rather than physical shipment.
• ITEM_PRESENT_ON_DRAFT_SHIPMENT_WITH_ZERO_QUANTITY now states plainly that the line item appears on a draft shipment with quantity 0.

Error codes themselves are unchanged, so existing handling in your apps continues to work.