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
Viewing the inventory adjustment history for an item variation.
Batching inventory adjustments and information retrieval.
The Inventory API is only available for applications using
Square-Version2018-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_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 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
InventoryPhysicalCount are identical. But in most cases, item loss, accidental damage, and human error create discrepancies between
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
An online customer buys one collar on the store website (built with Square APIs), which moves one unit from
An accident in the store damages two collars so the seller manually transitions two units from
WASTEbecause 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.
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 firstname.lastname@example.org 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.