Fulfillment Outbound Dynamic Sandbox Guide

The Selling Partner API dynamic sandbox environment allows you to test your applications 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 Multi-Channel Fulfillment Outbound sandbox environment. For more information about the Selling Partner API sandbox environments, refer to Selling Partner API sandbox.

Dynamic sandbox support for Fulfillment Outbound APIs

The dynamic sandbox is supported for the Fulfillment Outbound API version 2020-07-01 API section. Making calls to the dynamic sandbox is identical to making production API calls, except that 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 Fulfillment Outbound operations return dynamic responses:

• cancelFulfillmentOrder
• createFulfillmentOrder
• getFulfillmentOrder
• getFulfillmentPreview
• getPackageTrackingDetails
• listAllFulfillmentOrders
• updateFulfillmentOrder
• deliveryOffers

📘

Static responses

The dynamic sandbox backend service doesn't return dynamic responses for all Fulfillment Outbound operations. The service returns static responses for createFulfillmentReturn, getFeatureInventory, getFeatures, getFeatureSKU, and listReturnReasonCodes. Any successful call to one of these operations always returns the same static response for that operation.

To use the dynamic sandbox, direct your calls to the appropriate sandbox endpoint instead of the production endpoint. You can test all the tutorials that are listed in the production Fulfillment Outbound Use Case Guide in the dynamic sandbox.

Test the Fulfillment Outbound sandbox with the FBA Inventory dynamic sandbox

You can use the FBA Inventory dynamic sandbox and Fulfillment Outbound dynamic sandbox together to leverage SKU, and inventory and fulfillment policy checks on dynamic sandbox orders. To use the two environments together, you must first create inventory items in the FBA Inventory dynamic sandbox.

📘

Note

When you use the FBA Inventory and Fulfillment Outbound sandbox APIs together, HOLD orders are initially created in the Received state, and SHIP orders are created in the Planning state (except when Invalid).

Testing using the Fulfillment Outbound dynamic sandbox

You can use the submitFulfillmentOrderStatusUpdate sandbox-only operation as a mechanism to emulate the order fulfillment process.

To test using this mechanism, follow these steps:

1. Choose one of the test scenarios. Each scenario lists a sequence of fulfillmentOrderStatus changes that occur when a Fulfillment Outbound order is processed.

2. Call the createFulfillmentOrder operation to create a fulfillment order.

3. Call the getFulfillmentOrder operation to validate the order and return the fulfillmentOrderStatus value.

4. Repeat the following steps until the fulfillmentOrderStatus returns the final value in your chosen scenario:

   a. Call the submitFulfillmentOrderStatusUpdate operation to move the order to the next stage of the fulfillment order process. This means you must set the fulfillmentOrderStatus in the request to the next appropriate value indicated in the scenario that you have chosen to test.

   b. Call the getFulfillmentOrder operation to validate the order and return the fulfillmentOrderStatus.

Test scenarios

The following scenarios list the sequence of fulfillmentOrderStatus value changes as your fulfillment order is processed.

• Fulfillment order is fully or partially completed:

  Received → Planning → Processing → Complete or CompletePartialled

• Fulfillment order is unfulfillable

  Received → Planning → Unfulfillable

• Fulfillment order is cancelled

  Received → Planning → Cancelled

When the fulfillmentOrderStatus for a specific fulfillment order has reached the final value in one of the test scenarios, you can't process additional updates.

Tutorial: Create and complete a sandbox Fulfillment Outbound order

This tutorial explains how to create a sandbox order and move it through the fulfillment process using the submitFulfillmentOrderStatusUpdate sandbox-only operation.

📘

Note

The submitFulfillmentOrderStatusUpdate operation is only for test purposes. If you use it in a production call, you get an HTTP 403 error response.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you're making calls. For more information, refer to Authorizing Selling Partner API Applications.
• The Amazon Fulfillment role assigned to your developer profile.
• The Amazon Fulfillment role selected in theApp registration page for your application.

Step 1: Choose a test scenario

Each scenario lists a sequence of changes to the fulfillmentOrderStatus value that occur as your fulfillment outbound order is processed.

Step 2: Create a test fulfillment order

To create a test fulfillment order, call the createFulfillmentOrder operation.

Step 3: Validate order status

To validate the order and return the fulfillmentOrderStatus value, which should be Received, call the getFulfillmentOrder operation.

Step 4: Ensure order status returns final value

Repeat step 5 and step 6 until the fulfillment order status returns the final value in your chosen scenario.

Step 5: Update order status

Call the submitFulfillmentOrderStatusUpdate operation and pass the following parameters:

Request

Path parameter

Body parameter

Request example

PUT https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/
fulfillmentOrders/f868fcbf-a73f-41dc-89dd-ac5a69ae2bb0

{
  "fulfillmentOrderStatus": "Planning"
}

Response

A successful response returns an HTTP 200 status code with an empty response body.

Response example

{}

Step 6: Validate the order status

To validate the order and return the fulfillmentOrderStatus, call the getFulfillmentOrder operation.

Request example

GET https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/
fulfillmentOrders/f868fcbf-a73f-41dc-89dd-ac5a69ae2bb0

Response example

A successful response returns an HTTP 200 status code with the valid order status for the specified sellerFulfillmentOrderId.

{
  "payload": {
    "fulfillmentOrder": {
      "sellerFulfillmentOrderId": "f868fcbf-a73f-41dc-89dd-ac5a69ae2bb0",
      "displayableOrderId": "TEST_ORDER_ID",
      "displayableOrderDate": "2022-10-07T14:49:45Z",
      "displayableOrderComment": "Test comment",
      "shippingSpeedCategory": "Standard",
      "destinationAddress": {
        "name": "Test Name",
        "addressLine1": "123 Main Street",
        "city": "Key West",
        "stateOrRegion": "FL",
        "countryCode": "US",
        "postalCode": "33040"
      },
      "fulfillmentAction": "Ship",
      "receivedDate": "2023-03-15T22:41:34Z",
      "fulfillmentOrderStatus": "Received",
      "statusUpdatedDate": "2023-03-15T22:41:46Z",
      "notificationEmails": [],
      "featureConstraints": []
    },
    "fulfillmentOrderItems": [
      {
        "cancelledQuantity": 0,
        "quantity": 5,
        "sellerFulfillmentOrderItemId": "OrderItemID",
        "sellerSku": "TEST-SKU-001",
        "unfulfillableQuantity": 0
      }
    ],
    "fulfillmentShipments": [],
    "returnItems": [],
    "returnAuthorizations": []
    "paymentInformation": [
        {
            "paymentMode":"CreditCard",
            "paymentTransactionId" : "TRANSID-20231012-1110",
            "paymentDate": "2020-01-09T19:46:45.809Z"
        }
    ]
  }
}

Response example - Invalid Input (HTTP status code 400)
The order is unable to move to the provided status state

{
  "errors": [
    {
      "code": "InvalidInput",
      "message": "Unable to place object in state",
      "details": ""
    }
  ]
}

Response example - Invalid Input (HTTP status code 400)
The provided order status is not valid

{
  "errors": [
    {
      "code": "InvalidInput",
      "message": "One validation error detected: Value 'Received' at 'fulfillmentOrderStatus' failed to satisfy constraint: Member must satisfy enum value set: [Unfulfillable, Received, CompletePartialled, Cancelled, Processing, Invalid, Complete, Planning]",
      "details": ""
    }
  ]
}

Tutorial: Create and complete a sandbox Fulfillment Outbound order for a given Fulfillment Policy

This tutorial explains how to create a sandbox order for a given Fulfillment Policy and move it through the fulfillment process using the submitFulfillmentOrderStatusUpdate sandbox-only operation. This tutorial outlines the steps for FulfillmentPolicy = FillAllAvailable, but also applies to FillOrKill and FillAll policies.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API Applications.
• The Amazon Fulfillment role assigned to your developer profile.
• The Amazon Fulfillment role selected in the App registration page for your application.

Step 1: Create an inventory item

Call the 'createInventoryItem' API operation. Create the item or product that you will use to test the outbound order.

Step 2: Add inventory

Call the 'addInventory' API operation. Add the required inventory to the item or product from step 1.

Step 3: Create a test fulfillment order

To create a fulfillment order that you can use to test the item and quantity (from step 1 and step 2, call the createFulfillmentOrder operation and add FulfillmentPolicy = FillAllAvailable to your request. This policy creates the order in a Planning state.

Step 4: Validate order status

To validate your order and return the fulfillmentOrderStatus value, which should be Planning, call the getFulfillmentOrder operation.

Step 5: Validate inventory values

To validate that fulfillableQuantity is reduced by the order quantity and pendingCustomerOrderQuantity is increased by the order quantity, call the getInventorySummaries operation.

Step 6: Update the order status

Call the submitFulfillmentOrderStatusUpdate operation and pass the following parameters:

Request

Path parameter

Body parameter

Request example

PUT https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/
fulfillmentOrders/f868fcbf-a73f-41dc-89dd-ac5a69ae2bb0

{
  "fulfillmentOrderStatus": "Processing"
}

Response

A successful response returns an HTTP 200 status code with an empty response body.

Response example

{}

Step 7: Complete the Order

To complete the order, repeat step 6 and add fulfillmentOrderStatus: Complete to your request.

Step 8: Validate the inventory values

When fulfillableQuantity is reduced by the order quantity and pendingCustomerOrderQuantity is 0, there is no pending action on order fulfillment and the order is out for delivery.

To validate that fulfillableQuantity is reduced by the order quantity and pendingCustomerOrderQuantity is 0, which indicates that there is no pending action on order fulfillment and the order is out for delivery, call the getInventorySummaries operation.

Tutorial: Get dynamic delivery offers

To complete this tutorial, refer to the Fulfillment Outbound API Use Case Guide.

Business scenarios

Use the following business scenarios to test your Fulfillment Outbound orders. These scenarios represent the main use cases for order creation and fulfillment for seller listings.

⭐

Tip

The API scenarios listed in the following table refer to the North American (NA) dynamic sandbox endpoints. To use these examples in other regions, you must replace the endpoints with your region's SP-API sandbox endpoint.

Frequently asked questions

• Do I need a new set of credentials to access the sandbox?

No. You can use your existing set of production app credentials to access the dynamic sandbox APIs.

• Can I use the sandbox for load or performance testing?

No. The service is intended for developer code integration and validation testing. It's not designed for load testing.

• Do I need a different catalog and inventory setup for sandbox testing?

The Fulfillment Outbound Sandbox supports developer testing with any SKU that has unlimited inventory. We highly recommend that developers use the FBA Inventory dynamic sandbox to create inventory items, so developers can test with their own SKUs while they observe inventory movements as their merchant fulfillment (MCF) test orders are virtually completed.

• I used the createFulfillmentOrder operation to create a sandbox Fulfillment Outbound order. Why is my order not fulfilled?

When you test in the sandbox, you must call the submitFulfillmentOrderStatusUpdate operation to move orders through the fulfillment process.

• Can I view sandbox orders on the Seller Central portal?

No. Sandbox orders are test orders and cannot be viewed on Seller Central. You can retrieve sandbox orders by directing calls to listAllFulfillmentOrders or getFulfillmentOrder with the appropriate sandbox endpoints.

• Can I create sandbox orders for any marketplace?

Yes. The sandbox does not validate marketplaceId, which means you can test order fulfillment with any valid country-state-zip combination in the delivery address.

• Does the sandbox support Export or Fees?

No. The sandbox doesn't support Exports or Fees.

• Are all currencies and weights supported?

No. The sandbox only returns the currency in USD and the weight in pounds.

• What feature constraints are allowed?

The sandbox allows featureConstraints BB and BLOCK_AMZL for all marketplaces.

• Does the sandbox support notifications for orders and shipments?

No. Notifications are not sent for sandbox fulfillment orders. To retrieve updated order date, direct your getFulfillmentOrder call to the appropriate sandbox endpoint.