Retrieve Inventory Quantities for Item Variations

Applies to: Inventory API

Learn how to retrieve in-stock quantities for a specific item variation.

Business owners need to check their available stock regularly. The Inventory API makes this easy with two options: RetrieveInventoryCount for single items and BatchRetrieveInventoryCounts for multiple items at once. You can also look up historical physical counts from specific dates.

The RetrieveInventoryCount endpoint retrieves the in-stock quantity of a specified item variation. That is, the inventory state of the item variation is IN_STOCK.

The BatchRetrieveInventoryCounts endpoint is more flexible than checking single items. You can use it to:

• Check multiple inventory states (not just IN_STOCK).
• Get counts for different locations, items, or states at once.

You only need to provide one search criteria, but you can combine them to get more specific results. For example:

• Search by location to see all items at specific locations, regardless of state.
• Search by item to see stock levels across all locations and inventory states.
• Search by state to see all items in a particular status (such as IN_STOCK or SOLD).

The input to a BatchRetrieveInventoryCounts call is declared as the request body. You can combine different types of input parameters in a single call to narrow the scope of the results.

The following example shows how to check stock levels for multiple items at one location. You need to provide:

• A list of item IDs you want to check.
• The location ID where you want to check.

When you manually count your inventory and update Square with the numbers, the system creates a record of this count. Each count gets a unique ID (physical_count_id).

To find a specific count ID and its details:

1. Use the RetrieveInventoryChanges endpoint.
2. Look through the results for your recorded count.
3. Use the record ID and RetrieveInventoryPhysicalCount to retrieve complete details.

For an example, see Inspect the Inventory Change History.

The following example retrieves the inventory physical count reconciled with the physical count ID of NN3V72CNW2ZTHKUOM2HUIGNS as the URL path parameter value: