FBA Inventory Dynamic Sandbox Guide
Test your FBA Inventory API v1 integration code.
Use the Fulfillment by Amazon (FBA) Inventory API v1 dynamic sandbox to test integration code in a safe, isolated developer environment without affecting production data or initiating real-world events. The dynamic sandbox routes requests to a sandbox backend that can return realistic responses based on the request parameters. By sending requests to the sandbox endpoints instead of the SP-API endpoints, you can test standard workflows without impacting production data.
This guide introduces the available dynamic sandbox operations for the FBA Inventory sandbox environment. For more information about the Selling Partner API sandbox environments, refer to the Selling Partner API sandbox.
Dynamic sandbox support in the FBA Inventory API
The dynamic sandbox is supported in the FBA Inventory API v1 version. Making calls to the dynamic sandbox is identical to making production API calls except you must direct your requests to a dynamic sandbox endpoint for your region instead of the production endpoint. Refer to Selling Partner API sandbox endpoints for the supported sandbox endpoints.
The following FBA Inventory operations return a dynamic response:
The getInventorySummaries
response includes the following dynamic fields; all other fields have a static null (0
) value:
ASIN
fnSku
sellerSku
fulfillableQuantity
totalReservedQuantity
pendingCustomerOrderQuantity
totalQuantity
To dynamically change the response fields for fulfillableQuantity
, totalReservedQuantity
, and pendingCustomerOrderQuantity
, you must create and manage virtual fulfillment orders using the Fulfillment Outbound dynamic sandbox.
Testing using the FBA Inventory dynamic sandbox
To use FBA Inventory dynamic sandbox, you must create a virtual inventory item and add it to the sandbox environment using the following control APIs:
-
Create an inventory item using
createInventoryItem
. -
Add your inventory item to your sandbox environment using
addInventory
. -
Repeat step 1 and step 2 until you have enough items in your sandbox to conduct your tests.
-
View your sandbox catalog items and associated inventory by calling
getInventorySummaries
.
Tutorial: Create, modify, and review virtual inventory
This tutorial shows you how to use the FBA Inventory API v1 dynamic sandbox (along with the Fulfillment Outbound dynamic sandbox) to create, modify, and review inventory in your virtual sandbox environment.
Prerequisites
To complete this tutorial, you must have:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
-
The marketplace ID for the marketplace from which you want inventory summaries.
-
A test environment that is configured to connect to the Selling Partner dynamic sandbox endpoints for your region.
-
(Optional) Your code integrated with the Fulfillment Outbound APIs. This is so that you can observe inventory movements by calling the
getInventorySummaries
operation while virtually fulfilling orders using the Fulfillment Outbound dynamic sandbox. If you opt for code integration, your Developer App profile must assign the following roles to your application:- Inventory and Order Tracking (FBA Inventory)
- Product Listing (FBA Inventory)
- Amazon Fulfillment (Fulfillment Outbound)
Step 1: Create a virtual product or item
Call the createInventoryItem
operation by passing the following parameters:
Body parameters
Parameter | Description | Required |
---|---|---|
sellerSku |
Identifies an item in the given marketplace. SellerSKU is qualified by the seller's SellerId Type: string |
Yes |
marketplaceId |
The marketplace in which the item is created. Type: < string > array |
Yes |
productName |
Name or details of the item you want to create. Type: string |
Yes |
To create a virtual sandbox inventory item, use the sandbox control createInventoryItem
operation, as shown in the following example request. This operation creates one inventory item at a time.
Request example
POST https://sandbox.sellingpartnerapi-na.amazon.com/fba/inventory/v1/items
BODY:
{
"sellerSku": "PermanentMarker-Red",
"marketplaceId": "ATVPDKIKX0DER",
"productName": "Red Permanent Marker"
}
Response
A successful response returns a 200 status code with an empty response body.
Step 2. Add virtual inventory for items
Call the addInventory
operation by passing the following parameters:
Parameters
Header parameter | Description | Required |
---|---|---|
x-amzn-idempotency-token |
Unique request identifier. Type: string |
Yes |
Body parameter | Description | Required |
---|---|---|
sellerSku |
Identifies an item in the specified marketplace. SellerSKU is qualified by the seller's SellerId Type: string |
Yes |
marketplaceId |
The marketplace where you created the item. Type: < string > array |
Yes |
quantity |
The quantity of virtual inventory. Type: string |
Yes |
To add inventory to the item you created in step 1, use the sandbox control addInventory
operation, as shown in the following example request. To create additional virtual items and inventory, repeat step 1 and step 2.
Request example
POST: https://sandbox.sellingpartnerapi-na.amazon.com/v1/items/inventory
BODY:
{
"inventoryItems": [
{
"sellerSku": "PermanentMarker-Red",
"marketplaceId": "ATVPDKIKX0DER",
"quantity": 5
},
{
"sellerSku": "PermanentMarker-Blue",
"marketplaceId": "ATVPDKIKX0DER",
"quantity": 5
}
]
}
Response
A successful response returns a 200 status code with an empty response body.
Step 3. Validate inventory summaries
Review the inventory details for the items you created in step 1 and step 2. Call the getInventorySummaries
operation by passing the following parameters. To learn more about the complete functions of this API, refer to the FBA Inventory API v1 reference.
Request
Query parameters
Parameter | Description | Required |
---|---|---|
sellerSku |
Seller SKU for the item. Type: string |
Yes |
marketplaceIds |
The marketplace ID for the marketplace from which you want inventory summaries. Only one marketplace ID is allowed. Type: < string > array |
Yes |
details |
Set to true to return inventory summaries with additional summarized inventory details and quantities. Type: Boolean |
Yes |
granularityType |
The granularity type for the inventory aggregation level. Possible values: Marketplace Type: string |
Yes |
granularityId |
The granularity ID for the specified granularity type. When granularityType is Marketplace , you must specify the marketplaceIds .Type: string |
Yes |
Request example
GET https://sandbox.sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?details=true&granularityType=Marketplace&granularityId=ATVPDKIKX0DER&sellerSkus=PermanentMarker-Red&marketplaceIds=ATVPDKIKX0DER
Note
The FBA Inventory API v1 dynamic sandbox automatically creates a virtual Amazon Standard Identification Number (ASIN) and fulfillment network stock keeping unit (FNSKU). These values are fictitious and do not appear in Amazon production.
Response
{
"pagination": {
"nextToken": "seed"
},
"payload": {
"granularity": {
"granularityType": "Marketplace",
"granularityId": "ATVPDKIKX0DER"
},
"inventorySummaries": [
{
"asin": "B00T9QONN1",
"fnSku": "B00T9QONN1",
"sellerSku": "PermanentMarker-Red",
"condition": "NewItem",
"inventoryDetails": {
"fulfillableQuantity": 5,
"inboundWorkingQuantity": 0,
"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": "2023-01-24T23: 40: 39Z",
"productName": "PermanentMarker-Red",
"totalQuantity": 5
}
]
}
}
Step 4. Deplete your virtual inventory
To complete this step, use the Fulfillment Outbound dynamic sandbox to virtually create and fulfill an off-Amazon fulfillment order that depletes the inventory items you created in step 1 and step 2.
Step 5. Review your updated inventory levels
Use the getInventorySummaries
operation to review your updated inventory levels based upon the orders that you completed in the Fulfillment Outbound dynamic sandbox.
Request
Query parameters
Parameter | Description | Required |
---|---|---|
sellerSku |
Seller SKU for the item. Type: string |
Yes |
marketplaceIds |
The marketplace ID for the marketplace for which you want inventory summaries. Only one marketplace ID is allowed. Type: < string > array |
Yes |
details |
Set to true to return inventory summaries with additional summarized inventory details and quantities. Otherwise, this returns inventory summaries only (default value). Type: Boolean |
Yes |
granularityType |
The granularity type for the inventory aggregation level. Possible values are: Marketplace Type: string |
Yes |
granularityId |
The granularity ID for the specified granularity type. When granularityType is Marketplace , you must specify the marketplaceIds .Type: string |
Yes |
Request example
GET https://sandbox.sellingpartnerapi-na.amazon.com/fba/inventory/v1/summaries?details=true&granularityType=Marketplace&granularityId=ATVPDKIKX0DER&sellerSkus=PermanentMarker-Red&marketplaceIds=ATVPDKIKX0DER
Response
{
"pagination": {
"nextToken": "seed"
},
"payload": {
"granularity": {
"granularityType": "Marketplace",
"granularityId": "ATVPDKIKX0DE"
},
"inventorySummaries": [
{
"asin": "B00T9QONN1",
"fnSku": "B00T9QONN1",
"sellerSku": "PermanentMarker-Red ",
"condition": "NewItem",
"inventoryDetails": {
"fulfillableQuantity": 0,
"inboundWorkingQuantity": 0,
"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": "2023-01-24T23: 40: 39Z",
"productName": "PermanentMarker-Red",
"totalQuantity": 0
}
]
}
}
Step 6. Delete inventory items from your sandbox
To delete an inventory item from your sandbox environment, use the sandbox control deleteInventoryItem
operation.
Important
You can only delete an inventory item if values for
fulfillableQuantity
,totalReservedQuantity
, andpendingCustomerOrderQuantity
are0
. To deplete all of your inventory, use the Fulfillment Outbound dynamic sandbox to complete orders.
Request
Query parameters
Parameter | Description | Required |
---|---|---|
sellerSku |
Seller SKU for the item. Type: string |
Yes |
marketplaceId |
The marketplace ID for the marketplace for which you created the item. Type: < string > array |
Yes |
Request example
DELETE: https://sellingpartnerapi-na.amazon.com/fba/inventory/v1/items/deleteInventoryItem
BODY:
{
"marketplaceId": "ATVPDKIKX0DE",
"sellerSku": "PermanentMarker-Red"
}
Response
A successful response returns a 200 status code with an empty response body.
Updated about 2 months ago