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:
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
, andlistReturnReasonCodes
. 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 theReceived
state, andSHIP
orders are created in thePlanning
state (except whenInvalid
).
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:
-
Choose one of the test scenarios. Each scenario lists a sequence of
fulfillmentOrderStatus
changes that occur when a Fulfillment Outbound order is processed. -
Call the
createFulfillmentOrder
operation to create a fulfillment order. -
Call the
getFulfillmentOrder
operation to validate the order and return thefulfillmentOrderStatus
value. -
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 thefulfillmentOrderStatus
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 thefulfillmentOrderStatus
.
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
orCompletePartialled
-
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
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 < |
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:
- 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
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 < |
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 case | API | Key response details | Notes |
---|---|---|---|
Preview 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. 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/fulfillmentOrders | 200 (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/fulfillmentOrders | Order 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. | -- |
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}/cancel | 200 (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}/status | 200 | To 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.
Updated 3 months ago