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


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

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.

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/batch-retrieve-changes
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/v2/inventory/batch-retrieve-changes \
  -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": [
      "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?