Fulfillment Outbound Dynamic Sandbox Guide

How to use the Selling Partner API dynamic sandbox to test fulfillment outbound operations.

Overview

The Selling Partner API dynamic sandbox environment allows you to test your applications without affecting production data or triggering 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 in the Fulfillment Outbound APIs

The dynamic sandbox is supported in the Fulfillment Outbound API 2020-07-01 version API section. 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 Fulfillment Outbound operations return dynamic responses:

📘

Static responses

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

All of the tutorials detailed in the production Fulfillment Outbound Use Case Guide can also be tested using the dynamic sandbox by directing calls to the appropriate sandbox endpoint instead of the production endpoint.

Testing using the Fulfillment Outbound dynamic sandbox

You can use the new submitFulfillmentOrderStatusUpdate sandbox-only operation as a mechanism to control emulating the completion of the order fulfillment process.

Here are the high level steps to test using this mechanism:

  1. Choose one of the testing scenarios listed. Each scenario lists a sequence of changes to the fulfillmentOrderStatus value that occur during the processing of a fulfillment outbound order.

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

  3. Call the getFulfillmentOrder operation to validate the order and return the fulfillmentOrderStatus value, which should be "Received".

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

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

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

Testing scenarios

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

Fulfillment order is completed fully or partially

Received → Planning → Processing → Complete or CompletePartialled

Fulfillment order is unfulfillable

Received → Planning → Unfulfillable

Fulfillment order was cancelled

Received → Planning → Cancelled

Once the fulfillmentOrderStatus for a specific fulfillment order has reached the final value in one of the testing scenarios, no further updates can be processed.

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 sandox-only operation. This operation is for testing only and must be directed to a sandbox endpoint. An attempt to use it in production will result in an HTTP 403 error response.

Prerequisites

To complete this tutorial, you will need:

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

Step 1: Choose one of the testing scenarios

Each scenario lists a sequence of changes to the fulfillmentOrderStatus value that occur during the processing of a fulfillment outbound order.

Step 2: Create a test fulfillment order in the sandbox

Call the createFulfillmentOrder operation to create a fulfillment order for testing.

Step 3: Validate the status of the order

Call the getFulfillmentOrder operation to validate the order and return the fulfillmentOrderStatus value, which should be "Received".

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

Step 5: Update the order status using the submitFulfillmentOrderStatusUpdate sandbox-only operation

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 status of the order

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

Request example

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


Response example - Success (HTTP status code 200)

The response contains the valid order status for the provided 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": []
  }
}


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": "1 validation error detected: Value 'Receivd' at 'fulfillmentOrderStatus' failed to satisfy constraint: Member must satisfy enum value set: [Unfulfillable, Received, CompletePartialled, Cancelled, Processing, Invalid, Complete, Planning]",
      "details": ""
    }
  ]
}

Business scenarios

The following business scenarios are supported in the fulfillment outbound orders for testing purposes. These are the main use cases supported by the test orders focused primarily on order creation and fulfillment using seller listings.

The API scenarios listed in the table refer to the North American (NA) dynamic sandbox endpoints. To use these examples in other regions you will need to replace the endpoints with your region's Selling Partner API sandbox endpoint.

Use Case API Key Response Details Notes
Get a preview of an order. POST https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview Fulfillment fees, shipment shipping, and estimated delivery dates for all supported shipping speeds. Optional to use, helpful to show the fees/promised speeds to end shopper.
Create an order in Hold or Ship status in different ship speeds [Priority,Expedited,Standard]. POST https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders 200 OK if accepted, 400 error with details if rejected. Hold/Ship option to either reserve and hold up to 14 days or release the order to be processed for shipping.
List the order details for up to 50 orders at a time. GET https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders Order with item details. Returns the seller order ID which can be used to call the getFulfillmentOrder operation.
Get the order details for the specifiedsellerFulfillmentOrderId. 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.
Get the 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 the order with the specified sellerFulfillmentOrderId. PUT https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId} 200 OK if accepted, 400 error with details if rejected. Primarily used when orders are in Hold status and can be updated to Ship status. Here are the other properties that can be updated using this operation in the sandbox environment: displayableOrderId, displayableOrderDate, displayableOrderComment, shippingSpeedCategory, fulfillmentAction, destinationAddress, notificationEmails, items-quantity - (quantity can only be reduced and must be non-zero).
Cancel the order with the specified sellerFulfillmentOrderId. PUT https://sandbox.sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/{sellerFulfillmentOrderId}/cancel 200 OK if accepted, 400 error with details if rejected. The order can be canceled 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}/status 200 OK To simulate the real time status update of an order, use this sandbox-only API to move the fulfillmentOrderStatus through state changes such as those indicated in Testing scenarios.

Frequently Asked Questions (FAQ)

  • Do we need a new set of credentials to access the sandbox?
    No, the existing set of app credentials used in production can be used to access the dynamic sandbox APIs.

  • Can the sandbox be used for load or performance testing?
    No. The service is intended for developer code integration and validation testing. It is not designed for load testing.

  • Is there a different catalog and inventory setup needed for sandbox SKUs?
    There is no catalog or inventory setup needed. Any product stock keeping unit (SKU) can be used and has unlimited inventory available for creating orders.

  • I used the createFulfillmentOrder operation to create a sandbox fulfillment outbound order. Why is it not being fulfilled?
    When you test in the sandbox you must call the submitFulfillmentOrderStatusUpdate operation to move orders through the fulfillment process.

  • Can sandbox orders be viewed 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 the listAllFulfillmentOrders or getFulfillmentOrder operations to the appropriate sandbox endpoints.

  • Can sandbox orders be created for any marketplace?
    Yes. The sandbox does not validate "marketplaceId" which means you can test order fulfillment using ANY valid country-state-zip combination in the delivery address.

  • Does the sandbox support Export or Fees?
    The sandbox does not 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?
    Notifications are not sent for sandbox fulfillment orders. Updated order data must be retrieved by directing a call to the getFulfillmentOrder operation to the appropriate sandbox endpoint.