Inventory API

What it Does

Adjust inventory quantities and review inventory changes for products in a Square catalog.

The Square Inventory API replaces the Connect v1 Inventory API and introduces new functionality:

  • Moving item variation quantities through predefined states (such as, from IN_STOCK to WASTE).

  • Viewing the inventory adjustment history for an item variation.

  • Batching inventory adjustments and information retrieval.

Requirements and limitations Permalink Get a link to this section

  • The Inventory API is only available for applications using Square-Version 2018-09-18 or later. For more information, see Versioning in Square APIs.

  • Inventory quantities can only be tracked on Square CatalogItemVariations. For more information about the Square catalog, see Catalog API: What It Does.

  • The Inventory API does not support the tracking of fractional quantities, subcomponents, ingredients, and product bundling.

  • Anonymous Inventory API calls are not allowed. All Inventory API calls must include an authorization token for the targeted Square account.

  • All applications using OAuth to read inventory information must have INVENTORY_READ permission for the targeted Square account.

  • Applications using OAuth to modify inventory quantities must have INVENTORY_WRITE permission for the targeted Square account.

Product components Permalink Get a link to this section

The Inventory API accepts inventory adjustments and physical counts for quantities of item variations and transitions those quantities to the relevant inventory state. Key data types for the Inventory API are:

  • InventoryCount. The computed quantity of an item variation at a specific location with a specific inventory state.

  • InventoryAdjustment. The quantity of an item variation transitioning from one inventory state to another.

  • InventoryPhysicalCount. The verified quantity of an item variation at a specific location with a specific state as determined by a manual count or trusted system.

  • InventoryTransfer. The quantity of an item variation transitioning from one location to another. Inventory transfer information is currently read-only in the API. Transfer functionality is limited to the items dashboard for retail subscribers.

  • SourceApplication. Information about the application that applied an inventory change. SourceApplication records provide traceability for inventory changes.

InventoryCount and InventoryPhysicalCount objects are similar in that they both indicate the current quantity of a CatalogItemVariation, but InventoryPhysicalCount is a provided value and InventoryCount is a computed value.

InventoryPhysicalCount represents the quantity of an item variation that is physically present. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system. InventoryCount represents the quantity Square thinks is present based on the known sequence of inventory adjustments since the last physical count update. In an ideal world, the values of InventoryCount and InventoryPhysicalCount are identical. But in most cases, item loss, accidental damage, and human error create discrepancies between InventoryCount and InventoryPhysicalCount.

As a specific example, consider the case where a seller receives a quantity of dog collars into inventory, sells some, accidentally damages some, and then recounts them at the end of the day to reconcile the inventory. Initially, there are no collars in stock. Before opening the store in the morning, the seller receives 100 small leather collars from a vendor and adds them to inventory by transitioning 100 units from NONE to IN_STOCK to make them available for sale. During the course of the day:

  • The seller sells three collars to a customer in the store using Square Point of Sale, which automatically moves three units from IN_STOCK to SOLD.

  • An online customer buys one collar on the store website (built with Square APIs), which moves one unit from IN_STOCK to SOLD.

  • An accident in the store damages two collars so the seller manually transitions two units from IN_STOCK to WASTE because they are no longer available for sale.

At this point, the calculated inventory count for small leather collars in the IN_STOCK state is: 100 − 3 − 1 − 2 = 94 units.

At the end of the day, the seller closes the store and counts all the small leather collars in the store and finds that there are only 93 collars available for sale. To reconcile the computed and verified counts, the seller pushes the physical count to Square, which updates the IN_STOCK quantity of small leather collars to 93.


The main point to understand is that inventory adjustments are handled by moving quantities of item variations at a given location from one state to another rather than assigning and decrementing a single quantity.

Decimal quantities Permalink Get a link to this section

The quantity field can support quantities up to five decimal places. Use Connect version 2019-05-08 or later to use decimal quantities.

Developers can start building support for decimal quantities in their applications ahead of decimal support in the Point of Sale application and the Seller Dashboard. You should use decimal quantities only for testing and development. If you want to see decimal quantities displayed in the Seller Dashboard, create a separate account specifically for testing and development, and then contact to enable decimal quantities in your test account.

If a legacy Point of Sale application attempts to read a decimal quantity on inventory counts or adjustments, the quantity is rounded down to the nearest integer. For example, 2.5 becomes 2 and –2.5 becomes –3.

Related topics Permalink Get a link to this section