Inventory API

Inspect the Inventory Change History

To inspect the history of inventory adjustments and the reset of physical counts for a specific item variation (for example, to create an audit log), call the RetrieveInventoryChanges endpoint, while specifying the item variation with the catalog_object_id URL path parameter value. You can also use the location_id query parameter to filter the result by location.

To inspect the history of inventory changes for multiple item variations, call the BatchRetrieveInventoryChanges endpoint, while specifying the desired input parameters in the request body.

Retrieve inventory changes of a specific item variation Permalink Get a link to this section

The cURL example retrieves the change history of the item variation identified by its ID value of 6F4K33KPNUVDWKZ43KUIFH6K.

Request: Retrieve the change history of a single item variation Permalink Get a link to this section

Retrieve Inventory Changes
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/inventory/6F4K33KPNUVDWKZ43KUIFH6K/changes \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Response: Retrieve the change history of a single item variation Permalink Get a link to this section

A successful response is shown as follows.

In this example, the history includes

  • An adjustment that adds 100 units to the inventory when the inventory state changed from NONE to IN_STOCK.

  • An adjustment that marks 2 units as damaged items when the inventory state changed from IN_STOCK to WASTE.

  • A reset of the in-stock count by an actual physical count.

{
  "changes": [
    {
      "type": "PHYSICAL_COUNT",
      "physical_count": {
        "id": "NN3V72CNW2ZTHKUOM2HUIGNS",
        "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "EF6D9SACKWBKZ",
        "quantity": "95",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        },
        "occurred_at": "2020-12-28T21:28:01.12289Z",
        "created_at": "2020-12-29T01:30:14.12291Z"
      }
    },
    {
      "type": "ADJUSTMENT",
      "adjustment": {
        "id": "L4UVSZ6XSLEMPKJI6IK4Y43Z",
        "from_state": "IN_STOCK",
        "to_state": "WASTE",
        "location_id": "EF6D9SACKWBKZ",
        "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
        "catalog_object_type": "ITEM_VARIATION",
        "quantity": "2",
        "occurred_at": "2020-12-18T21:19:00.12189Z",
        "created_at": "2020-12-18T21:19:51.12189Z",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        }
      }
    },
    {
      "type": "ADJUSTMENT",
      "adjustment": {
        "id": "HA4STFR47RAEORFWXHOYPRG5",
        "from_state": "NONE",
        "to_state": "IN_STOCK",
        "location_id": "EF6D9SACKWBKZ",
        "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
        "catalog_object_type": "ITEM_VARIATION",
        "quantity": "100",
        "occurred_at": "2020-12-18T21:10:00.12189Z",
        "created_at": "2020-12-18T21:10:34.12189Z",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        }
      }
    }
  ]
}

Retrieve inventory changes of multiple item variations Permalink Get a link to this section

The following cURL example retrieves the change history of the item variations identified by their ID values of 6F4K33KPNUVDWKZ43KUIFH6K and IJBAQDICELYUAUTHM352X3AI. The input values are specified in the catalog_object_ids of the request body.

Request: Retrieve inventory changes of multiple item variations Permalink Get a link to this section

Batch Retrieve Inventory Changes
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
curl https://connect.squareupsandbox.com/v2/inventory/batch-retrieve-changes \
  -X POST \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_object_ids": [
      "6F4K33KPNUVDWKZ43KUIFH6K",
      "IJBAQDICELYUAUTHM352X3AI"
    ]
  }'

Response: Retrieve inventory changes of multiple item variations Permalink Get a link to this section

A successful response is shown as follows. In this example, the change history includes:

  • An adjustment that adds 100 units of the first item variation (6F4K33KPNUVDWKZ43KUIFH6K) to the inventory when the inventory state changed from NONE to IN_STOCK.

  • An adjustment that marks 2 units of the first item variation (6F4K33KPNUVDWKZ43KUIFH6K) as damaged items when the inventory state changed from IN_STOCK to WASTE.

  • A reset of the in-stock count of the first item variation (6F4K33KPNUVDWKZ43KUIFH6K) by an actual physical count of 95.

  • A reset of the in-stock count of the second item variation (IJBAQDICELYUAUTHM352X3AI) that adds 75 units to the inventory.

{
  "changes": [
    {
      "type": "ADJUSTMENT",
      "adjustment": {
        "id": "HA4STFR47RAEORFWXHOYPRG5",
        "from_state": "NONE",
        "to_state": "IN_STOCK",
        "location_id": "EF6D9SACKWBKZ",
        "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
        "catalog_object_type": "ITEM_VARIATION",
        "quantity": "100",
        "occurred_at": "2020-12-18T21:10:00.12189Z",
        "created_at": "2020-12-18T21:10:34.12189Z",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        }
      }
    },
    {
      "type": "ADJUSTMENT",
      "adjustment": {
        "id": "L4UVSZ6XSLEMPKJI6IK4Y43Z",
        "from_state": "IN_STOCK",
        "to_state": "WASTE",
        "location_id": "EF6D9SACKWBKZ",
        "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
        "catalog_object_type": "ITEM_VARIATION",
        "quantity": "2",
        "occurred_at": "2020-12-18T21:19:00.12189Z",
        "created_at": "2020-12-18T21:19:51.12189Z",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        }
      }
    },
    {
      "type": "PHYSICAL_COUNT",
      "physical_count": {
        "id": "YB3YFKVNO476NY3EFWHQDXB6",
        "catalog_object_id": "IJBAQDICELYUAUTHM352X3AI",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "EF6D9SACKWBKZ",
        "quantity": "75",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        },
        "occurred_at": "2020-12-18T21:56:00.12189Z",
        "created_at": "2020-12-18T21:56:31.12189Z"
      }
    },
    {
      "type": "PHYSICAL_COUNT",
      "physical_count": {
        "id": "NN3V72CNW2ZTHKUOM2HUIGNS",
        "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
        "catalog_object_type": "ITEM_VARIATION",
        "state": "IN_STOCK",
        "location_id": "EF6D9SACKWBKZ",
        "quantity": "95",
        "source": {
          "product": "EXTERNAL_API",
          "application_id": "sandbox-sq0idb-_nrujCaIUWI1tG41i2rRuw",
          "name": "Sandbox for sq0idp-oumq_1XqglftCHKsbhnvyw"
        },
        "occurred_at": "2020-12-28T21:28:01.12289Z",
        "created_at": "2020-12-29T01:30:14.12291Z"
      }
    }
  ]
}