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
expires after 30 secondsTo 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:
-
All inventory summaries with all available detail are returned when the
startDateTime
andsellerSkus
parameters are omitted. -
When
startDateTime
is provided, the operation returns inventory summaries that have changed after the date and time specified. ThesellerSkus
parameter is ignored.Avoid pagination errors
To avoid errors, use both
startDateTime
andnextToken
to get the next page of inventory summaries that have changed after the date and time specified. -
When the
sellerSkus
parameter is provided, the operation returns inventory summaries for only the specifiedsellerSkus
.
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
|
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:
-
The marketplace ID for the marketplace for which to return inventory summaries.
-
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:
|
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:
-
The marketplace ID for the marketplace for which to return inventory summaries.
-
A list of up to fifty
sellerSku
s 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
|
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 29 days ago