• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Batch retrieve inventory counts

Returns current counts for the provided CatalogObjects at the requested Locations.

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.

Required permissions: INVENTORY_READ

Request Body

Name Description
string [ ]

Filters results by CatalogObject ID. Only applied when set. Default: unset.

string [ ]

Filters results by Location ID. Only applied when set. Default: unset.


Provided as an RFC 3339 timestamp. Returns results whose calculated_at value is after the given time. Default: UNIX epoch (1970-01-01T00:00:00Z).

Examples for January 25th, 2020 6:27.34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00


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 guide for more information.

Response Fields

Name Description
Error [ ]

Any errors that occurred during the request.

InventoryCount [ ]

The current calculated inventory counts for the requested objects and locations.


The pagination cursor to be used in a subsequent request. If unset, this is the final response.

See the Pagination guide for more information.


You are viewing an old version of the API
POST /v2/inventory/batch-retrieve-counts
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/v2/inventory/batch-retrieve-counts \
  -X POST \
  -H 'Square-Version: 2020-06-25' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_object_ids": [
    "location_ids": [
    "updated_after": "2016-11-16T00:00:00.000Z"
Response JSON
  "errors": [],
  "counts": [
      "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "59TNP9SA8VGDA",
      "quantity": "79",
      "calculated_at": "2016-11-16T22:28:01.223Z"

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?