HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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:

  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:

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, and pendingCustomerOrderQuantity are 0. 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.