What It Does
Adjust inventory quantities and review inventory changes for products in a Square Catalog.
The Connect v2 Inventory API replaces the Connect v1 Inventory API and introduces new functionality:
Moving item variations quantities through predefined states (e.g., from
Viewing the inventory adjustment history for an item variation.
Batch inventory adjustments and information retrieval.
The Inventory API is only available for applications using
Square-Version2018-09-18 or later. See the Connect V2 API Versioning Overview for more details.
Inventory quantities can only be tracked on Square
CatalogItemVariations. See the Catalog API documentation for more information on the Square Catalog.
Inventory API does not support tracking for 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_READpermission for the targeted Square account.
Applications using OAuth to modify inventory quantities must have
INVENTORY_WRITEpermission for the targeted Square account.
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.
SourceApplicationrecords provide traceability for inventory changes.
InventoryPhysicalCount objects are similar in that they
both indicate the current quantity of a
InventoryPhysicalCount is a provided value and
InventoryCount is a
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
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
InventoryPhysicalCount are identical. But in most cases, item loss, accidental
damage, and human error will create discrepancies between
As a specific example, consider the case where a merchant receives a quantity of dog collars into inventory, sells some, accidentally damages some, and then re-counts them at the end of the day to reconcile their inventory. Initially, there are no collars in stock. Before opening the store in the morning, the merchant 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 merchant sells 3 collars to a customer in the store using Square Point of Sale, which automatically moves 3 units from
An online customer buys 1 collar on the store site (built with Square APIs), which moves 1 unit from
An accident in the store damages 2 collars so the merchant manually transitions 2 units from
WASTEbecause they are no longer available for sale.
At this point, the calculated inventory count for small leather collars in
IN_STOCK state is: 100 − 3 − 1 − 2 = 94 units.
At the end of the day, the merchant 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 merchant pushes the
physical count to Square, which updates the
IN_STOCK quantity of small leather
collars to 93.
The key thing 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.
As a beta function, the
quantity field can support quantities with up to 5 decimal places. Use Connect version
2019-05-08 or later to use decimal quantities.
We have beta launched decimal quantity support so that developers can start building support for decimal quantities in their apps ahead of decimal support in the Point of Sale app and the Dashboard. We recommend you use decimal quantities only for testing and development. If you would like to see decimal quantities displayed in the Dashboard, create a separate account specifically for testing and development, then contact email@example.com to enable decimal quantities in your test account.
If a Point of Sale app or Dashboard attempts to read a decimal quantity on inventory counts or adjustments, the quantity will be rounded down to the nearest integer. For example,
2.5 will become
-2.5 will become
Use the build guides below to integrate with Inventory API.