Retrieve Inventory Quantities for Item Variations

Applies to: Inventory API

Learn how to retrieve in-stock quantities for a specific item variation.

As part of running a business, a seller needs to occasionally inspect how many items are available. 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 in time.

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.

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.

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

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.

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.

A successful response is shown as follows. Because the inventory states aren't 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"
    }
  ]
}

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.

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

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.