How It Works
Take a deeper look at the the Inventory API.
Inventory API process flow
Inventory unit counts are calculated by applying all the adjustments received since the last recorded physical count. If no physical count has been recorded, the adjustments are applied with an assumed starting unit quantity of zero.
Inventory changes (including changes due to sales transactions) can be sent to
Square out of order. As a result, adjustments and physical count updates require
a client-specified RFC 3339 timestamp
(occurred_at
) so the inventory history can be ordered correctly.
Consider a situation where the Square Point of Sale application processes transactions in offline mode while a custom inventory management solution makes inventory adjustments through the API.
Assume that the related item variation starts with 100 IN_STOCK units.
At 13:10 GMT, the inventory management backend sends an
InventoryAdjustment
request using the Inventory API to record a sale through a non-Square system and move 3 units fromIN_STOCK
toSOLD
. At this point, there are 97IN_STOCK
units.At 13:20 GMT, the Square Point of Sale device goes offline. The seller sells 2 units in offline mode with a recorded transaction time of 13:20 GMT.
At 13:30 GMT, the inventory management backend sends an
InventoryPhysicalCount
request using the Inventory API to reconcile the computed quantity in the Square inventory service (97 units) with a verified physical quantity available for sale (90 units).At 13:35 GMT, the Square Point of Sale device reconnects to the Internet and pushes the offline sale to Square, which moves 2
IN_STOCK
units toSOLD
. Square applies the transaction results, with a client timestamp of 13:20 GMT, before theInventoryPhysicalCount
request that occurred at 13:30 GMT. Although the Point of Sale transaction was the last change sent to Square, theIN_STOCK
quantity is still 90 units, as indicated by the physical count update, because the last change according to the client timestamp was theInventoryPhysicalCount
request.At 13:40 GMT, the inventory management backend sends another
InventoryAdjustment
request using the Inventory API to move 2 fromIN_STOCK
toWASTE
because they are no longer suitable for sale. TheInventoryAdjustment
request has a client timestamp that happens after the count reconciliation so theIN_STOCK
count is now 88 units and theWASTE
count is 2 units.
Reconciliation with InventoryPhysicalCount
InventoryPhysicalCount
should only be used to reconcile the inventory count computed by Square with the results of performing a physical count or syncing with a trusted external system. Do not use InventoryPhysicalCount
to apply sequential adjustments to CatalogItemVariation
quantities. Retrieving an InventoryCount
from the server, modifying the count based on recent changes, and pushing the updated inventory count as an InventoryPhysicalCount
forces Square to ignore changes that might have occurred in the interim and results in inaccurate tracking.
Consider the case where the Square Point of Sale application captures a sale after the InventoryCount
request but before the InventoryPhysicalCount
update.
Assume that an application knows that 3 units were sold through a non-Square channel. The application calls the Inventory API and the InventoryCount
result indicates 10 units in the IN_STOCK
state. At the same time, the Square Point of Sale application captures a sale of 2 units and moves those 2 units from IN_STOCK
to SOLD
. There are now 8 units in the IN_STOCK
state.
Based on the InventoryCount
result, the application incorrectly believes there are currently 10 units in the IN_STOCK
state. If the application uses InventoryPhysicalCount
to reduce the IN_STOCK
quantity by 3, the final quantity of IN_STOCK
units is forced to be 7 units (10 IN_STOCK
units − 3 units sold externally) when it should be 5 units (10 IN_STOCK
units − 2 units sold through the Square Point of Sale application − 3 units sold externally).
The correct way to track sales through a non-Square system is to push an InventoryAdjustment
that moves units from IN_STOCK
to SOLD
. Inventory adjustments force Square systems to apply inventory changes in the correct order rather than explicitly overwriting the count. For example, by subtracting the 3 units sold externally after subtracting the 2 units sold through the Square Point of Sale application.
Batched state transitions
Square servers record inventory operations based on timestamps provided by the communicating client and batched updates succeed or fail as atomic operations. For example, consider the case where a single request batches the following changes for a single item variation:
100 units move from the
NONE
state to theIN_STOCK
state.5 units move from the
IN_STOCK
state to theWASTE
state.Record a physical count of 90 units.
Individual changes in a batched state are recorded based on their individual client timestamps, but they are applied (all or nothing) as a single request. Assuming that the inventory count for the targeted catalog item variation starts at zero:
100 units move from
NONE
toIN_STOCK
with a timestamp of 23:00 GMT, making the calculated inventory count 100.5 units move from
IN_STOCK
toWASTE
with a timestamp of 23:10 GMT, making the calculated inventory count 95.The system records a physical count of 90 units with a timestamp of 23:30 GMT, resetting the calculated inventory count to 90 rather than 95.
If all three changes succeed, the new calculated inventory count for IN_STOCK
units is 90. However, if any of the individual changes fail, the entire update fails and the calculated inventory count remains unchanged at zero.
Inventory quantities are also affected by Square payment APIs and Point of Sale applications. In the previous example, when the Square Point of Sale application records a transaction, it moves 3 units from the IN_STOCK
state to the SOLD
state. Assuming that the transaction timestamp places it after the batch update succeeds, the new calculated inventory count for IN_STOCK
units is 87.
Special InventoryState values
NONE
The NONE
state is not a true inventory state. NONE
is a from_state
placeholder to represent the fact that a given CatalogItemVariation
was introduced as new inventory. Inventory quantities can be transitioned from the NONE
state, but cannot be transitioned to the NONE
state.
IN_STOCK
The IN_STOCK
state does not represent a pool of available items decremented over time. Item variation quantities move into and out of the IN_STOCK
state as they do with other states. In general, when quantities move between states, the total quantity for that item variation across all states does not change. For example, consider the item variation "Small Leather Collar" with a total of 100 units. Initially all 100 units are in the IN_STOCK
state. If 3 units become damaged, there are still 100 units at the end of the day: 97 units in the IN_STOCK
state and 3 in the WASTE
state. The IN_STOCK
state is only special in that the Square Point of Sale application and Seller Dashboard use the quantity of item variations with the IN_STOCK
state to determine the number of units currently available for sale.
SOLD
SOLD
is a terminal state. When inventory items move to the SOLD
state, the units are no longer explicitly tracked. Transferring quantities from SOLD
to some other state introduces a new quantity into inventory rather than changing the quantity in the SOLD
state. For example, consider the case where "Small Leather Collar" has 100 units in the IN_STOCK
state. If 5 units are sold online and 3 units are sold in the store, there are 92 units tracked. If a customer returns 2 units to the store, there are 94 units tracked: 92 units with the IN_STOCK
state and 2 units with the RETURNED_BY_CUSTOMER
state.
Supported state transitions
Inventory state transitions represent real world changes to inventory quantities. As a result, some state changes are permitted (such as, IN_STOCK
to SOLD
) while others are not (such as, WASTE
to RETURNED_BY_CUSTOMER
). Square supports the following inventory state transitions:
From state | To state | Related event |
---|---|---|
NONE | IN_STOCK | A quantity of items was received and is available for sale. |
IN_STOCK | SOLD | A quantity of items was sold. |
IN_STOCK | WASTE | A quantity of items was damaged or lost and cannot be sold. |
UNLINKED_RETURN | IN_STOCK | A quantity of items was returned by the customer and is available for sale. The return is not affiliated with a specific transaction. |
UNLINKED_RETURN | WASTE | A quantity of items was returned by the customer and deemed to be unsellable. The return is not affiliated with a specific transaction. |
In addition to the support state transitions, the Inventory API might return additional read-only states as part of the change history for a given item variation. Transitions to or from read-only states can only be triggered from within Square products.
Automatic IN_STOCK adjustments
If inventory tracking is enabled in the Square Seller Dashboard, completing an itemized transaction with Square products automatically moves the quantity sold from the IN_STOCK
state to the SOLD
state.
For example, consider a Payment API request that references an Order object containing three catalog line items: a small leather dog collar, a 5-foot retractable leash, and Chewy chicken trainer treats.
When the Charge
endpoint processes the transaction, Square automatically adjusts the IN_STOCK
quantities by moving 1 unit of the small leather dog collar from IN_STOCK
to SOLD
, 1 unit of the 5-foot retractable leash from IN_STOCK
to SOLD
, and 2 units of Chewy chicken trainer treats from IN_STOCK
to SOLD
.
ignore_unchanged_counts flag
Requests to the BatchChangeInventory
endpoint include an ignore_unchanged_counts
flag. The ignore_unchanged_counts
flag tells Square to skip updates for the CatalogItemVariation
if nothing has changed. When the new physical count for a CatalogItemVariation
is the same as the previous physical count and no InventoryAdjustment
requests have been received between the two physical counts, the physical count update is skipped. The ignore_unchanged_counts
flag lets third-party systems push potentially redundant inventory counts to Square without polluting the Seller Dashboard with unnecessary adjustments.
The ignore_unchanged_counts
flag is enabled by default so developers do not inadvertently spam Square servers with redundant InventoryPhysicalCount
requests. Do not disable the ignore_unchanged_counts
flag unless the associated InventoryPhysicalCount
request represents a true reconciliation, such as an actual physical count by a person.