---
title: >-
  Inventory transfer webhooks include origin and destination location IDs, and
  mutation documentation clarified - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/inventory-transfer-webhooks-include-origin-and-destination-location-ids-and-mutation-documentation-clarified
  md: >-
    https://shopify.dev/changelog/inventory-transfer-webhooks-include-origin-and-destination-location-ids-and-mutation-documentation-clarified.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2026-05-05T14:52:02-04:00'
  postedAt: '2026-05-05T12:00:00-04:00'
  updatedAt: '2026-05-05T18:02:58-04:00'
  effectiveAt: '2026-05-05T12:00:00-04:00'
---

May 5, 2026

Tags:

* Admin GraphQL API
* 2026-04

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

Available now on the unstable API version. See the Inventory transfer webhook reference for details.

### Clarified documentation for inventoryTransferSetItems

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

* inventoryTransferSetItems is an upsert. Only the inventory items you include in lineItems are affected; line items already on the transfer that you don't reference are left 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.
* For each line item you reference, if its full quantity is still unallocated to a shipment, 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 — 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 cannot remove every line item from a READY\_TO\_SHIP transfer and that, to empty one, you should cancel it instead.
* ITEM\_FULLY\_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.