Applies to: Inventory API | Catalog API
Learn about using the Inventory API to adjust inventory quantities and review inventory changes for products in a Square catalog.
A Square seller maintains inventory to keep track of the quantity of products for sale or services for hire. Inventory tracking is essentially the process of moving quantities of item variations between the different inventory states. For example, when the online order for a leather collar and heavy sweater is processed, the on-hand quantities for leather collar and heavy sweater are automatically updated by moving the number of purchased units for each item variation from IN_STOCK to SOLD.
In addition to automatic inventory tracking, Square supports nuanced inventory tracking (such as receiving stock and marking waste) and reconciliation.
With inventory, the seller can get answers to questions like "How much do I have in store now?" and "How many of a particular item were lost?" Through historical data, the seller might even get a view of trends of how fast a particular product sells or how soon a product should be restocked.
For products or services to be tracked in an inventory, they must be defined as item variations in the Square catalog. In other words, a catalog defines what the seller has for sale, whereas an inventory describes how much the seller has in stock or has changed in stock. In the Seller Dashboard, managing the catalog and maintaining the inventory are integrated in the Item Library.
The Square Inventory API lets you create applications to manage Square inventories programmatically on behalf of Square sellers. Specifically, you can use the Inventory API to adjust inventory quantities and review inventory changes for products in a Square catalog. To track new products or services, you must enable your application to call the Catalog API to create appropriate items with required item variations.
The Inventory API exposes a set of objects to represent inventory adjustments and physical counts for quantities of products (as item variations) and transitions of stocked products to the relevant inventory state. These include the following key data types for the Inventory API:
- InventoryCount - It defines the computed quantity of an item variation at a specific location with a specific inventory state.
- InventoryAdjustment - It describes the quantity of an item variation transitioning from one inventory state to another.
- InventoryPhysicalCount - It defines 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 - It defines the quantity of an item variation transitioning from one location to another. Inventory transfer between locations is currently read-only information to the API. It's limited to the Seller Dashboard for items available for retail subscribers.
- SourceApplication - It describes the application that makes an inventory change and helps trace sources of inventory changes.
InventoryCount and InventoryPhysicalCount objects are similar in that they both describe 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 that 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 the 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're 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 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.