Inventory API

Retrieve Inventory Quantities for Item Variations

As part of running a business, a seller needs to inspect how many items are available from time to time. The Inventory API enables this by exposing RetrieveInventoryCount or its batched version of BatchRetrieveInventoryCounts. In addition, it allows for retrieving the inventory physical count as recorded at a particular point of time.

Retrieve the in-stock inventory count of an item variation Permalink Get a link to this section

The RetrieveInventoryCount endpoint retrieves the in-stock quantity of a specified item variation. That is, the inventory state of the item variation is IN_STOCK.

Request: Retrieve the inventory count of an item variation Permalink Get a link to this section

The following cURL example retrieves the in-stock quantity of an item variation in a given location. The specific item variation is identified by the URL path variable value of 6F4K33KPNUVDWKZ43KUIFH6K. The location is identified by the query parameter of location_id value.

Retrieve Inventory Count
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/inventory/6F4K33KPNUVDWKZ43KUIFH6K?location_id=EF6D9SACKWBKZ \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Response: Retrieve the inventory count of an item variation Permalink Get a link to this section

The successful request returns a response similar to the following, containing the current quantity of the specified item variation:

{
  "counts": [
    {
      "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "95",
      "calculated_at": "2020-12-29T01:30:14.12291Z"
    }
  ]
}

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

The BatchRetrieveInventoryCounts endpoint can be used to retrieve quantities of specified item variations in one or more inventory states, instead of just the single IN_STOCK state.

When calling the BatchRetrieveInventoryCounts endpoint, you can specify at least one input attribute and use the default values for all other input values.

  • If you specify location IDs, you retrieve inventory counts of all the item variations in all inventory states at the specified locations.

  • If you specify item variation IDs, you retrieve the inventory counts of the specified item variations in all available inventory states at all available locations.

  • If you specify inventory states, you retrieve inventory counts of all the item variations in the specified inventory states at all locations.

The input to a BatchRetrieveInventoryCounts call is declared as the request body. You can combine different types of input parameters in a single call to narrow the scope of the results.

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

The following cURL example retrieves the in-stock quantities of multiple item variations in a given location. The specific item variations are declared in the request body as entries of the catalog_object_ids list. The location is specified as an element of the location_ids list.

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

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

A successful response is shown as follows. Because the inventory states are not explicitly specified in the request body, the result includes all the available inventory states (that is, the IN_STOCK and WASTE inventory counts).

{
  "counts": [
    {
      "catalog_object_id": "IJBAQDICELYUAUTHM352X3AI",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "75",
      "calculated_at": "2020-12-18T21:56:31.12189Z"
    },
    {
      "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "WASTE",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "2",
      "calculated_at": "2020-12-18T21:19:51.12189Z"
    },
    {
      "catalog_object_id": "6F4K33KPNUVDWKZ43KUIFH6K",
      "catalog_object_type": "ITEM_VARIATION",
      "state": "IN_STOCK",
      "location_id": "EF6D9SACKWBKZ",
      "quantity": "95",
      "calculated_at": "2020-12-29T01:30:14.12291Z"
    }
  ]
}

Retrieve a reconciled inventory physical count Permalink Get a link to this section

An inventory physical count is stock quantity recorded from an in-person inspection, or the inventory reported by a trusted system considered to be the inventory master. A specific physical count update is identified by the {physical_count_id} path parameter of the RetrieveInventoryPhysicalCount endpoint URL.

The physical_count_id value is generated by the Inventory API when a BatchChangeInventory is called to reset the inventory count on a specified item variation with the physical count. You can call the RetrieveInventoryChanges endpoint and inspect the result to retrieve the desired physical_count_id value. For an example, see Inspect Inventory Change History.

Request: Retrieve a reconciled inventory physical count Permalink Get a link to this section

The following cURL example retrieves the inventory physical count reconciled with the physical count ID of NN3V72CNW2ZTHKUOM2HUIGNS as the URL path parameter value:

Retrieve Inventory Physical Count
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/inventory/physical-count/NN3V72CNW2ZTHKUOM2HUIGNS \
  -H 'Square-Version: 2021-03-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Response: Retrieve a reconciled inventory physical count Permalink Get a link to this section

A successful response is shown as follows:

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

Notice that the inventory physical count applies only to the IN_STOCK inventory count.