Inventory API

What It Does

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

Android
Backend

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 IN_STOCK to WASTE).

  • Viewing the inventory adjustment history for an item variation.

  • Batch 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. 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_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 will create discrepancies between InventoryCount and InventoryPhysicalCount.

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 IN_STOCK to SOLD.

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

  • An accident in the store damages 2 collars so the merchant manually transitions 2 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 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.

example-inventory-tracking

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.

Decimal quantities (BETA)
Permalink Get a link to this section

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 decimal-quantities-beta@squareup.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, and -2.5 will become -3.

Get started

Use the build guides below to integrate with Inventory API.