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

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

POST /v2/inventory/counts/batch-retrieve

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.

Permissions
INVENTORY_READ
 Try in API Explorer

Request Body

Example code
Name Description
catalog_object_ids
string [ ]

The filter to return results by CatalogObject ID. The filter is applicable only when set. The default is null.

Max Length 1000
location_ids
string [ ]

The filter to return results by Location ID. This filter is applicable only when set. 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).

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

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

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00
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 guide for more information.
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.
limit
integer (32-bit)

The number of records to return.

Min 1 Max 1000

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
counts
InventoryCount [ ]

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

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

See the Pagination guide for more information.

Examples

You are viewing an old version of the API
POST /v2/inventory/counts/batch-retrieve
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/inventory/counts/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_object_ids": [
      "W62UWFY35CWMYGVWK6TWJDNI"
    ],
    "location_ids": [
      "59TNP9SA8VGDA"
    ],
    "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"
    }
  ]
}