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

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

POST /v2/inventory/changes/batch-retrieve

Returns historical physical counts and adjustments based on the provided filter criteria.

Results are paginated and sorted in ascending order according their occurred_at timestamp (oldest first).

BatchRetrieveInventoryChanges is a catch-all query endpoint for queries that cannot be handled by other, simpler endpoints.

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 only applicable when set. The default value is null.

Max Length 500
location_ids
string [ ]

The filter to return results by Location ID. The filter is only applicable when set. The default value is null.
types
string [ ]

The filter to return results by InventoryChangeType values other than TRANSFER. The default value is [PHYSICAL_COUNT, ADJUSTMENT].
states
string [ ]

The filter to return ADJUSTMENT query results by InventoryState. This filter is only applied when set. The default value 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
updated_before
string

The filter to return results with their created_at or calculated_at value strictly before 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.
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.
changes
InventoryChange [ ]

The current calculated inventory changes 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/changes/batch-retrieve
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/inventory/changes/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_object_ids": [
      "W62UWFY35CWMYGVWK6TWJDNI"
    ],
    "location_ids": [
      "C6W5YS5QM06F5"
    ],
    "types": [
      "PHYSICAL_COUNT"
    ],
    "states": [
      "IN_STOCK"
    ],
    "updated_after": "2016-11-01T00:00:00.000Z",
    "updated_before": "2016-12-01T00:00:00.000Z"
  }'
Response JSON 
{
  "errors": [],
  "changes": [
    {
      "type": "PHYSICAL_COUNT",
      "physical_count": {
        "id": "46YDTW253DWGGK9HMAE6XCAO",
        "reference_id": "22c07cf4-5626-4224-89f9-691112019399",
        "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "C6W5YS5QM06F5",
        "quantity": "86",
        "source": {
          "product": "SQUARE_POS",
          "application_id": "416ff29c-86c4-4feb-b58c-9705f21f3ea0",
          "name": "Square Point of Sale 4.37"
        },
        "team_member_id": "LRK57NSQ5X7PUD05",
        "occurred_at": "2016-11-16T22:24:49.028Z",
        "created_at": "2016-11-16T22:25:24.878Z"
      }
    }
  ]
}