---
title: "BatchRetrieveInventoryCounts"
method: POST
path: "/v2/inventory/counts/batch-retrieve"
tags: ["Inventory"]
---

# BatchRetrieveInventoryCounts

`POST /v2/inventory/counts/batch-retrieve`

Returns current counts for the provided
[CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject)s at the requested
[Location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location)s.

Results are paginated and sorted in descending order according to their
`calculated_at` timestamp (newest first).

When `updated_after` is specified, only counts that have changed since that
time (based on the server timestamp for the most recent change) are
returned. This allows clients to perform a "sync" operation, for example
in response to receiving a Webhook notification.

## Request body

- BatchRetrieveInventoryCountsRequest
  - `catalog_object_ids` string[] — The filter to return results by `CatalogObject` ID. The filter is applicable only when set. The default is null.
  - `cursor` string — A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.
  - `location_ids` string[] — The filter to return results by `Location` ID. This filter is applicable only when set. The default is null.
  - `states` string[] — The filter to return results by `InventoryState`. The filter is only applicable when set. Ignored are untracked states of `NONE`, `SOLD`, and `UNLINKED_RETURN`. The default is null.
  - `updated_after` string — The filter to return results with their `calculated_at` value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).

## Response `200`

Success

- BatchRetrieveInventoryCountsResponse
  - `counts` InventoryCount[] — The current calculated inventory counts for the requested objects and locations.
    - `calculated_at` string — An RFC 3339-formatted timestamp that indicates when the most recent physical count or adjustment affecting the estimated count is received.
    - `catalog_object_id` string — The Square-generated ID of the [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked.
    - `catalog_object_type` string — The [type](https://developer.squareup.com/reference/square_2021-08-18/enums/CatalogObjectType) of the [CatalogObject](https://developer.squareup.com/reference/square_2021-08-18/objects/CatalogObject) being tracked. Tracking is only supported for the `ITEM_VARIATION` type.
    - `is_estimated` boolean — Whether the inventory count is for composed variation (TRUE) or not (FALSE). If true, the inventory count will not be present in the response of any of these endpoints: [BatchChangeInventory](https://developer.squareup.com/reference/square_2021-08-18/inventory-api/batch-change-inventory), [BatchRetrieveInventoryChanges](https://developer.squareup.com/reference/square_2021-08-18/inventory-api/batch-retrieve-inventory-changes), [BatchRetrieveInventoryCounts](https://developer.squareup.com/reference/square_2021-08-18/inventory-api/batch-retrieve-inventory-counts), and [RetrieveInventoryChanges](https://developer.squareup.com/reference/square_2021-08-18/inventory-api/retrieve-inventory-changes).
    - `location_id` string — The Square-generated ID of the [Location](https://developer.squareup.com/reference/square_2021-08-18/objects/Location) where the related quantity of items is being tracked.
    - `quantity` string — The number of items affected by the estimated count as a decimal string. Can support up to 5 digits after the decimal point.
    - `state` string — The current [inventory state](https://developer.squareup.com/reference/square_2021-08-18/enums/InventoryState) for the related quantity of items.
  - `cursor` string — The pagination cursor to be used in a subsequent request. If unset, this is the final response. See the [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination) guide for more information.
  - `errors` Error[] — Any errors that occurred during the request.
    - `category` string, required — The high-level category for the error.
    - `code` string, required — The specific code of the error.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.

---

[API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)