Retrieve Inventory Quantities for Item Variations

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.

Link to section

Retrieve the in-stock inventory count of an item variation

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.

Link to section

Request: Retrieve the inventory count of an item variation

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

Link to section

Response: Retrieve the inventory count of an item variation

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" } ] }
Link to section

Retrieve inventory counts of multiple item variations

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.

Link to section

Request: Retrieve inventory counts of multiple item variations

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

Link to section

Response: Retrieve inventory counts of multiple item variations

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).

Link to section

Retrieve a reconciled inventory physical count

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.

Link to section

Request: Retrieve a reconciled inventory physical count

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

Link to section

Response: Retrieve a reconciled inventory physical count

A successful response is shown as follows:

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