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

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.

Required permissions INVENTORY_READ

Request Body

Name Description
catalog_object_ids
string [ ]

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

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.

location_ids
string [ ]

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

states
string [ ]

Filters ADJUSTMENT query results by InventoryState. Only applied when set. Default: unset.

types
string [ ]

Filters results by InventoryChangeType. Default: [PHYSICAL_COUNT, ADJUSTMENT]. TRANSFER is not supported as a filter.

updated_after
string

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

updated_before
string

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

Response Fields

Name Description
changes
Inventory​Change [ ]

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.

errors
Error [ ]

Any errors that occurred during the request.

Examples

You are viewing an old version of the API
POST /v2/inventory/batch-retrieve-changes
cURL
  • cURL
  • Ruby
  • Python
curl https://connect.squareup.com/v2/inventory/batch-retrieve-changes \
  -X POST \
  -H 'Square-Version: 2019-11-20' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -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"
        },
        "employee_id": "LRK57NSQ5X7PUD05",
        "occurred_at": "2016-11-16T22:24:49.028Z",
        "created_at": "2016-11-16T22:25:24.878Z"
      }
    }
  ]
}

Share Feedback

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