FBA Inventory Dynamic Sandbox Guide

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:

• createInventoryItem
• addInventory
• deleteInventoryItem
• getInventorySummaries

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:

1. Create an inventory item using createInventoryItem.

2. Add your inventory item to your sandbox environment using addInventory.

3. Repeat step 1 and step 2 until you have enough items in your sandbox to conduct your tests.

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

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

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

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

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, and pendingCustomerOrderQuantity are 0. To deplete all of your inventory, use the Fulfillment Outbound dynamic sandbox to complete orders.

Request

Query parameters

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.