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
Retrieve inventory changes of multiple item variations

Retrieve inventory changes of a specific item variation
Request: Retrieve the change history of a single item variation
Response: Retrieve the change history of a single item variation
Retrieve inventory changes of multiple item variations
Request: Retrieve inventory changes of multiple item variations
Response: Retrieve inventory changes of multiple item variations

Link to section
Retrieve inventory changes of a specific item variation

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

Link to section
Request: Retrieve the change history of a single item variation

Retrieve Inventory Changes

curl https://connect.squareupsandbox.com/v2/inventory/6F4K33KPNUVDWKZ43KUIFH6K/changes \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Link to section
Response: Retrieve the change history of a single item variation

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

{
  "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"
        }
      }
    }
  ]
}

Link to section
Retrieve inventory changes of multiple item variations

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.

Link to section
Request: Retrieve inventory changes of multiple item variations

Batch Retrieve Inventory Changes

1
2
3
4
5
6
7
8
9
10
11

curl https://connect.squareupsandbox.com/v2/inventory/changes/batch-retrieve \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "catalog_object_ids": [
      "6F4K33KPNUVDWKZ43KUIFH6K",
      "IJBAQDICELYUAUTHM352X3AI"
    ]
  }'

Link to section
Response: Retrieve inventory changes of multiple item variations

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

{
  "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"
      }
    }
  ]
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Inspect the Inventory Change History

On this page

On this page

Link to section
Retrieve inventory changes of a specific item variation

Link to section
Request: Retrieve the change history of a single item variation

Link to section
Response: Retrieve the change history of a single item variation

Link to section
Retrieve inventory changes of multiple item variations

Link to section
Request: Retrieve inventory changes of multiple item variations

Link to section
Response: Retrieve inventory changes of multiple item variations

On this page

Docs

Inspect the Inventory Change History

On this page

On this page

Link to section Retrieve inventory changes of a specific item variation

Link to section Request: Retrieve the change history of a single item variation

Link to section Response: Retrieve the change history of a single item variation

Link to section Retrieve inventory changes of multiple item variations

Link to section Request: Retrieve inventory changes of multiple item variations

Link to section Response: Retrieve inventory changes of multiple item variations

On this page

Link to section
Retrieve inventory changes of a specific item variation

Link to section
Request: Retrieve the change history of a single item variation

Link to section
Response: Retrieve the change history of a single item variation

Link to section
Retrieve inventory changes of multiple item variations

Link to section
Request: Retrieve inventory changes of multiple item variations

Link to section
Response: Retrieve inventory changes of multiple item variations