Migrate to Updated API Entities

Applies to: Inventory API

Learn which updated Inventory API endpoints to call to migrate from deprecated endpoint URLs.

As the Inventory API evolves, some of the API entities are updated, some are deprecated for backward compatibility, and some are retired and no longer supported. The following information can help you migrate to updated API entities until they're retired.

The following endpoints have updated URLs to conform to the standard REST API convention. Their deprecated URLs are now part of the respective deprecated endpoints with the Deprecated prefix in their names. Support of these deprecated endpoints ends when they're retired in about 12 months.

Each pair of the updated endpoints and the corresponding deprecated endpoints share the same behavior.

Starting with Square version 2026-07-15, movement of stock between seller locations is represented as an ADJUSTMENT type InventoryChange with explicit locations, and the TRANSFER representation is retired:

• The TRANSFER value of InventoryChangeType, the InventoryTransfer object, and the RetrieveInventoryTransfer endpoint are retired. RetrieveInventoryTransfer returns an error at Square version 2026-07-15 or later.
• InventoryAdjustment.location_id is retired and replaced by from_location_id and to_location_id. For single-location adjustments, both fields contain the same location ID.
• Movement that was previously split into a synthetic TRANSFER and ADJUSTMENT pair (movement that crosses locations and states, such as a return received at a different location) is returned as a single ADJUSTMENT.

Requests made with earlier Square versions continue to receive and write the legacy TRANSFER shape without changes.

The following example shows how the same movement of 5 units between two locations is represented at old and new Square versions:

{
  "type": "ADJUSTMENT",
  "adjustment": {
    "id": "UDMOEO78BG6K2P4JOSLEBCGD",
    "from_state": "IN_STOCK",
    "to_state": "IN_STOCK",
    "from_location_id": "EF6D9SACKWBKZ",
    "to_location_id": "9BXNEQGVGHK8A",
    "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
    "catalog_object_type": "ITEM_VARIATION",
    "quantity": "5",
    "occurred_at": "2026-07-16T14:20:00.000Z",
    "created_at": "2026-07-16T14:20:04.000Z"
  }
}

To migrate:

• Reads - Query the change history with types=["ADJUSTMENT"]. Transfer-like changes are the adjustments whose from_location_id and to_location_id differ. (The types=["TRANSFER"] filter isn't supported at any Square version.)
• Writes - Write an ADJUSTMENT with matching states and differing locations instead of relying on Square products to create transfers.
• RetrieveInventoryTransfer - Use RetrieveInventoryAdjustment with the adjustment ID instead.