HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Fulfillment Outbound Dynamic Sandbox Guide

Use the SP-API dynamic sandbox to test Fulfillment Outbound operations.

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:

📘

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:

    ReceivedPlanningProcessingComplete or CompletePartialled

  • Fulfillment order is unfulfillable

    ReceivedPlanningUnfulfillable

  • Fulfillment order is cancelled

    ReceivedPlanningCancelled

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:

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

Parameter Description Required
sellerFulfillmentOrderId The identifier assigned to the item when the test fulfillment order was created.

Type: string

Yes

Body parameter

Parameter Description Required
fulfillmentOrderStatus The current status of the fulfillment order.

Type: enum < FulfillmentOrderStatus >

Yes

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:

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

Parameter Description Required
sellerFulfillmentOrderId The identifier assigned to the item when the test fulfillment order was created.

Type: string

Yes

Body parameter

Parameter Description Required
fulfillmentOrderStatus The current status of the fulfillment order.

Type: enum < FulfillmentOrderStatus >

Yes

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.

Use caseAPIKey response detailsNotes
Preview an order.POST https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/previewFulfillment fees, shipment shipping, and estimated delivery dates for all supported shipping speeds.Optional. Shows fees and promised speeds to shopper.
Create an order in HOLD or SHIP status for different ship speeds (Priority, Expedited,Standard).POST https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders200 (if accepted) or 400 with details (if rejected).HOLD to reserve and hold up to 14 days; SHIP to release the order to for shipment processing.
List order details for up to 50 orders.GET https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrdersOrder with item details.Returns the seller order ID, which you can use to call getFulfillmentOrder.
Get order details for sellerFulfillmentOrderId.GET https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}Fulfillment details for the line items in the order, including serial number tracking, package ID, and shipment details.None
Get package and tracking details for the specified package number. The packageNumber is returned as part of the getFulfillmentOrder response.GET https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/tracking?packageNumber={packageNumber}Carrier information, estimated date, and tracking information.The tracking number is fictional and not trackable.
Update order with the specified sellerFulfillmentOrderId.PUT https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}200 (if accepted) or 400 with details (if rejected).Use when orders are in HOLD status, but can be updated to SHIP status. You can update these sellerFulfillmentOrderId properties in the sandbox environment: displayableOrderId, displayableOrderDate, displayableOrderComment, shippingSpeedCategory, fulfillmentAction, destinationAddress, notificationEmails, items-quantity (you can only reduce quantity, and it cannot be 0).
Cancel an order with the specified sellerFulfillmentOrderId.PUT https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/cancel200 (if accepted). 400 with details (if rejected).You can cancel the order when the status is Planning or Received.
Update the fulfillment order status for the specified order.PUT https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/status200To simulate the real-time status update of an order, use this sandbox-only API to move fulfillmentOrderStatus through state changes, such as those listed in Test scenarios.

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.