HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

FBA Inventory API Use Case Guide

Programmatically retrieve information about inventory in Amazon's fulfillment network.

API Version: v1

What is the FBA Inventory API?

The FBA Inventory API lets you track the real-time availability of your inventory in Amazon's fulfillment network at the marketplace level. You can get details such as listing condition and inventory quantities such as fulfillable, inbound, reserved, unfulfillable, and researching. This API is available globally.

How to use the FBA Inventory API

🚧

nextToken will expire in 30 seconds

To avoid errors, use nextToken to get the next page within 30 seconds.

The FBA Inventory API requires the Product Listing role.

The getInventorySummaries operation returns a list of inventory summaries. The summaries returned depend on the presence or absence of the startDateTime and sellerSkus query parameters:

  1. All inventory summaries with all available detail are returned when the startDateTime and sellerSkus parameters are omitted.

  2. When startDateTime is provided, the operation returns inventory summaries that have changed after the date and time specified. The sellerSkus parameter is ignored.

🚧

Avoid pagination errors

To avoid errors, use both startDateTime and nextToken to get the next page of inventory summaries that have changed after the date and time specified.

  1. When the sellerSkus parameter is provided, the operation returns inventory summaries for only the specified sellerSkus.

Tutorial: Get all available inventory summaries with all available detail

This tutorial shows you how to use the FBA Inventory API to return all the available inventory summaries with full details. This corresponds to number 1 in How to use the FBA Inventory API.

Prerequisites

To complete this tutorial you will need:

  • The marketplace ID for the marketplace for which to return inventory summaries.

Get all available inventory summaries with full details

To return all available inventory summaries with full details, call the getInventorySummaries operation of the FBA Inventory API, passing the following query parameters:

Parameter Description Required
details Set to true to return inventory summaries with additional summarized inventory details and quantities. Otherwise, returns inventory summaries only (default value). Yes. Must be set to true.
granularityType The granularity type for the inventory aggregation level.
Possible values: Marketplace. 		Yes.
granularityId The granularity ID for the specified granularity type. When granularityType is Marketplace, you must specify the marketplaceId. Yes.
marketplaceIds The marketplace ID for the marketplace for which to return inventory summaries. Only one marketplace ID is allowed. Yes.
nextToken String token returned in the response of your previous request. The token expires after 30 seconds. No.

Request example:

GET https://sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?details=true&granularityType=Marketplace&granularityId=ATVPDKIKX0DER&marketplaceIds=ATVPDKIKX0DER

A successful response includes the following in the payload for each sellerSku:

Name Description
sellerSku The seller SKU for the item.
fnSku Amazon's fulfillment network SKU identifier. Fulfillment network stock keeping units (FNSKUs) are unique identifiers assigned by Amazon to products stored in and fulfilled from Amazon fulfillment centers.
asin The Amazon Standard Identification Number (ASIN) of an item. You can find the ASIN on the product detail page.
productName The localized language product title of the item within the specified marketplace.
lastUpdatedTime The date and time that any quantity was last updated.
totalQuantity The total number of units in an inbound shipment or in Amazon fulfillment centers.
fulfillableQuantity The item quantity that can be picked, packed, and shipped.
inboundWorkingQuantity The number of units in an inbound shipment for which you have notified Amazon.
inboundShippedQuantity The number of units in an inbound shipment that you have notified Amazon about and have provided a tracking number.
inboundReceivingQuantity The number of units that have not yet been received at an Amazon fulfillment center for processing, but are part of an inbound shipment with some units that have already been received and processed.
totalReservedQuantity The total number of units in Amazon's fulfillment network that are currently being picked, packed, and shipped; or are sidelined for measurement, sampling, or other internal processes.
pendingCustomerOrderQuantity The number of units reserved for customer orders.
pendingTransshipmentQuantity The number of units being transferred from one fulfillment center to another.
fcProcessingQuantity The number of units that have been sidelined at the fulfillment center for additional processing.
totalUnfulfillableQuantity The total number of units in Amazon's fulfillment network in unsellable condition.
customerDamagedQuantity The number of units in customer damaged disposition.
warehouseDamagedQuantity The number of units in warehouse damaged disposition.
distributorDamagedQuantity The number of units in distributor damaged disposition.
carrierDamagedQuantity The number of units in carrier damaged disposition.
defectiveQuantity The number of units in defective disposition.
expiredQuantity The number of units in expired disposition.
totalResearchingQuantity The total number of units currently being researched in Amazon's fulfillment network.
researchingQuantityBreakdown A list of quantity details for items currently being researched that includes
  • researchingQuantityInShortTerm (1-10 days)
  • researchingQuantityInMidTerm (11-20 days)
  • researchingQuantityInLongTerm (21 days or longer).

Response example:

{
  "pagination": {
    "nextToken": "seed"
  },
  "payload": {
    "granularity": {
      "granularityType": "Marketplace",
      "granularityId": "ATVPDKIKX0DER"
    },
    "inventorySummaries": [
      {
        "asin": "B00T9QONN1",
        "fnSku": "B00T9QONN1",
        "sellerSku": "msku314best",
        "condition": "NewItem",
        "inventoryDetails": {
          "fulfillableQuantity": 66,
          "inboundWorkingQuantity": 21,
          "inboundShippedQuantity": 0,
          "inboundReceivingQuantity": 0,
          "reservedQuantity": {
            "totalReservedQuantity": 0,
            "pendingCustomerOrderQuantity": 0,
            "pendingTransshipmentQuantity": 0,
            "fcProcessingQuantity": 0
          },
          "researchingQuantity": {
            "totalResearchingQuantity": 0,
            "researchingQuantityBreakdown": [
              {
                "name": "researchingQuantityInShortTerm",
                "quantity": 0
              },
              {
                "name": "researchingQuantityInMidTerm",
                "quantity": 0
              },
              {
                "name": "researchingQuantityInLongTerm",
                "quantity": 0
              }
            ]
          },
          "unfulfillableQuantity": {
            "totalUnfulfillableQuantity": 0,
            "customerDamagedQuantity": 0,
            "warehouseDamagedQuantity": 0,
            "distributorDamagedQuantity": 0,
            "carrierDamagedQuantity": 0,
            "defectiveQuantity": 0,
            "expiredQuantity": 0
          }
        },
        "lastUpdatedTime": "2018-03-31T23: 40: 39Z",
        "productName": "CalciumPowder",
        "totalQuantity": 87
      }
    ]
  }
}

Tutorial: Get all available inventory summaries that have changed

This tutorial shows you how to use the FBA Inventory API to return all the available inventory summaries that have changed since the specified start date and time. This corresponds to number 2 in How to use the FBA Inventory API.

Prerequisites

To complete this tutorial you will need:

  1. The marketplace ID for the marketplace for which to return inventory summaries.

  2. The start date and time to use as the basis for returning inventory summaries that have changed.

Get all available inventory summaries that have changed

📘

startDateTime required

startDateTime is required to get the next page of inventory summaries that have changed after the date and time specified.

To return all available inventory summaries that have changed, call the getInventorySummaries operation of the FBA Inventory API, passing the following query parameters:

Parameter Description Required
details Set to true to return inventory summaries with additional summarized inventory details and quantities. Otherwise, returns inventory summaries only (default value). No.
granularityType The granularity type for the inventory aggregation level.
Possible values: Marketplace. 		Yes.
granularityId The granularity ID for the specified granularity type. When granularityType is Marketplace, you must specify the marketplaceId. Yes.
startDateTime

A start date and time in ISO 8601 format. If specified, all inventory summaries that have changed since then are returned. You must specify a date and time that is no earlier than 18 months prior to the date and time of the request.

Note: Changes in the following are not detected:

  • inboundWorkingQuantity
  • inboundShippedQuantity
  • inboundReceivingQuantity

 Yes.
marketplaceIds The marketplace ID for the marketplace for which to return inventory summaries. Only one marketplace ID is allowed. Yes.
nextToken String token returned in the response of your previous request. The token expires after 30 seconds. No.

Request example:

GET https://sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?granularityType=Marketplace&granularityId=ATVPDKIKX0DER&startDateTime=2018-03-27T23:40:39Z&marketplaceIds=ATVPDKIKX0DER

A successful response includes the following in the payload for each sellerSku. Note that because the detail parameter was not specified in the request example and defaults to false, additional summarized inventory details and quantities are not returned.

Name Description
sellerSku The seller SKU for the item.
fnSku Amazon's fulfillment network SKU identifier. Fulfillment network stock keeping units (FNSKUs) are unique identifiers assigned by Amazon to products stored in and fulfilled from Amazon fulfillment centers.
asin The Amazon Standard Identification Number (ASIN) of an item. You can find the ASIN on the product detail page.
productName The localized language product title of the item within the specified marketplace.
lastUpdatedTime The date and time that any quantity was last updated.
totalQuantity The total number of units in an inbound shipment or in Amazon fulfillment centers.

Response example:

{
  "pagination": {
    "nextToken": "seed"
  },
  "payload": {
    "granularity": {
      "granularityType": "Marketplace",
      "granularityId": "ATVPDKIKX0DER"
    },
    "inventorySummaries": [
      {
        "asin": "B00T9QONN1",
        "fnSku": "B00T9QONN1",
        "sellerSku": "msku314best",
        "condition": "NewItem",
        "lastUpdatedTime": "2018-03-31T23: 40: 39Z",
        "productName": "CalciumPowder",
        "totalQuantity": 87
      }
    ]
  }
}

Tutorial: Get inventory summaries for the specified seller SKUs

This tutorial shows you how to use the FBA Inventory API to return inventory summaries for one or more (up to 50) specified sellerSku. This corresponds to number 3 in How to use the FBA Inventory API.

Prerequisites

To complete this tutorial you will need:

  1. The marketplace ID for the marketplace for which to return inventory summaries.

  2. A list of up to fifty sellerSkus for which to return inventory summaries.

Get inventory summaries with additional details for the specified Seller SKUs

To return inventory summaries with full details for the specified SKUs, call the **getInventorySummaries** operation of the FBA Inventory API, passing the following query parameters:

Parameter Description Required
details Set to true to return inventory summaries with additional summarized inventory details and quantities. Otherwise, returns inventory summaries only (default value). Yes. Must be set to true.
granularityType The granularity type for the inventory aggregation level.
Possible values: Marketplace. 		Yes.
granularityId The granularity ID for the specified granularity type. When granularityType is Marketplace, you must specify the marketplaceId. Yes.
sellerSkus A list of seller SKUs for which to return inventory summaries. You can specify up to 50 SKUs. Yes.
marketplaceIds The marketplace ID for the marketplace for which to return inventory summaries. Only one marketplace ID is allowed. Yes.

Request example:

GET https://sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?details=true&granularityType=Marketplace&granularityId=ATVPDKIKX0DER&sellerSkus=msku314best%2Cmsku271good&marketplaceIds=ATVPDKIKX0DER

A successful response includes the following in the payload for each of the specified sellerSkus:

Name Description
sellerSku The seller SKU for the item.
fnSku Amazon's fulfillment network SKU identifier. Fulfillment network stock keeping units (FNSKUs) are unique identifiers assigned by Amazon to products stored in and fulfilled from Amazon fulfillment centers.
asin The Amazon Standard Identification Number (ASIN) of an item. You can find the ASIN on the product detail page.
productName The localized language product title of the item within the specified marketplace.
lastUpdatedTime The date and time that any quantity was last updated.
totalQuantity The total number of units in an inbound shipment or in Amazon fulfillment centers.
fulfillableQuantity The item quantity that can be picked, packed, and shipped.
inboundWorkingQuantity The number of units in an inbound shipment for which you have notified Amazon.
inboundShippedQuantity The number of units in an inbound shipment that you have notified Amazon about and have provided a tracking number.
inboundReceivingQuantity The number of units that have not yet been received at an Amazon fulfillment center for processing, but are part of an inbound shipment with some units that have already been received and processed.
totalReservedQuantity The total number of units in Amazon's fulfillment network that are currently being picked, packed, and shipped; or are sidelined for measurement, sampling, or other internal processes.
pendingCustomerOrderQuantity The number of units reserved for customer orders.
pendingTransshipmentQuantity The number of units being transferred from one fulfillment center to another.
fcProcessingQuantity The number of units that have been sidelined at the fulfillment center for additional processing.
totalUnfulfillableQuantity The total number of units in Amazon's fulfillment network in unsellable condition.
customerDamagedQuantity The number of units in customer damaged disposition.
warehouseDamagedQuantity The number of units in warehouse damaged disposition.
distributorDamagedQuantity The number of units in distributor damaged disposition.
carrierDamagedQuantity The number of units in carrier damaged disposition.
defectiveQuantity The number of units in defective disposition.
expiredQuantity The number of units in expired disposition.
totalResearchingQuantity The total number of units currently being researched in Amazon's fulfillment network.
researchingQuantityBreakdown A list of quantity details for items currently being researched that includes
  • researchingQuantityInShortTerm (1-10 days)
  • researchingQuantityInMidTerm (11-20 days)
  • researchingQuantityInLongTerm (21 days or longer).

Response example:

{
  "pagination": {
    "nextToken": "seed"
  },
  "payload": {
    "granularity": {
      "granularityType": "Marketplace",
      "granularityId": "ATVPDKIKX0DER"
    },
    "inventorySummaries": [
      {
        "asin": "B00T9QONN1",
        "fnSku": "B00T9QONN1",
        "sellerSku": " msku314best",
        "condition": "NewItem",
        "inventoryDetails": {
          "fulfillableQuantity": 66,
          "inboundWorkingQuantity": 21,
          "inboundShippedQuantity": 0,
          "inboundReceivingQuantity": 0,
          "reservedQuantity": {
            "totalReservedQuantity": 0,
            "pendingCustomerOrderQuantity": 0,
            "pendingTransshipmentQuantity": 0,
            "fcProcessingQuantity": 0
          },
          "researchingQuantity": {
            "totalResearchingQuantity": 0,
            "researchingQuantityBreakdown": [
              {
                "name": "researchingQuantityInShortTerm",
                "quantity": 0
              },
              {
                "name": "researchingQuantityInMidTerm",
                "quantity": 0
              },
              {
                "name": "researchingQuantityInLongTerm",
                "quantity": 0
              }
            ]
          },
          "unfulfillableQuantity": {
            "totalUnfulfillableQuantity": 0,
            "customerDamagedQuantity": 0,
            "warehouseDamagedQuantity": 0,
            "distributorDamagedQuantity": 0,
            "carrierDamagedQuantity": 0,
            "defectiveQuantity": 0,
            "expiredQuantity": 0
          }
        },
        "lastUpdatedTime": "2018-03-31T23: 40: 39Z",
        "productName": "CalciumPowder",
        "totalQuantity": 87
      },
      {
        "asin": "B00T9QONN2",
        "fnSku": "B00T9QONN2",
        "sellerSku": " msku271good",
        "condition": "NewItem",
        "inventoryDetails": {
          "fulfillableQuantity": 6,
          "inboundWorkingQuantity": 2,
          "inboundShippedQuantity": 0,
          "inboundReceivingQuantity": 0,
          "reservedQuantity": {
            "totalReservedQuantity": 0,
            "pendingCustomerOrderQuantity": 0,
            "pendingTransshipmentQuantity": 0,
            "fcProcessingQuantity": 0
          },
          "researchingQuantity": {
            "totalResearchingQuantity": 0,
            "researchingQuantityBreakdown": [
              {
                "name": "researchingQuantityInShortTerm",
                "quantity": 0
              },
              {
                "name": "researchingQuantityInMidTerm",
                "quantity": 0
              },
              {
                "name": "researchingQuantityInLongTerm",
                "quantity": 0
              }
            ]
          },
          "unfulfillableQuantity": {
            "totalUnfulfillableQuantity": 0,
            "customerDamagedQuantity": 0,
            "warehouseDamagedQuantity": 0,
            "distributorDamagedQuantity": 0,
            "carrierDamagedQuantity": 0,
            "defectiveQuantity": 0,
            "expiredQuantity": 0
          }
        },
        "lastUpdatedTime": "2018-04-01T23: 40: 39Z",
        "productName": "CalciumPowder",
        "totalQuantity": 8
      }
    ]
  }
}

General Recommendation

NextToken in GetInventorySummariesResponse

To avoid errors, use nextToken to get the next page within 30 seconds.

Pagination in GetInventorySummariesResponse

When a call to the **getInventorySummaries** operation produces a nextToken, then there are inventories that have not been encountered yet and you can get them on the subsequent calls. You iterate through the Inventories using the nextToken token provided in successive responses. All inventory has been traversed, only after the pagination is returned in response. This means the inventorySummaries list can be empty but still produce a nextToken.

Examples:

Even if there are no inventories in the inventorySummaries list, there is a nextToken:

{
  "response": {
    "pagination": {
      "nextToken": "XXXXXXXXX"
    },
    "payload": {
      "granularity": {
        ...
      },
      "inventorySummaries": []
    }
  }
}

The getInventorySummaries operation is considered done only when the pagination is not returned in the response:

{
  "response": {
    "payload": {
      "granularity": {
        ...
      },
      "inventorySummaries": []
    }
  }
}

Updated about 1 month ago