• 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/batch-retrieve-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.


Permissions
INVENTORY_READ
Try in API Explorer
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.

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.

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/batch-retrieve-counts
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/v2/inventory/batch-retrieve-counts \
  -X POST \
  -H 'Square-Version: 2020-08-26' \
  -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"
    }
  ]
}

Share Feedback

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