Vendor Direct Fulfillment Dynamic Sandbox Guide
Use the Selling Partner API dynamic sandbox to test vendor direct fulfillment 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 production endpoints, you can test standard workflows without impacting production data.
This guide introduces the available dynamic sandbox operations for the Vendor Direct Fulfillment APIs. For more information about the Selling Partner API sandbox environments, refer to Selling Partner API sandbox.
Dynamic sandbox support in the Vendor Direct Fulfillment APIs
The dynamic sandbox is supported in the following Vendor Direct Fulfillment API sections:
- The Vendor Direct Fulfillment Orders API 2021-12-28 version supports all of the equivalent V1 production operations.
- The Vendor Direct Fulfillment Shipping API 2021-12-28 version supports all of the equivalent V1 production operations.
Static responses
The dynamic sandbox backend service does not yet return dynamic responses for all Vendor Direct Fulfillment Shipping operations. The service returns static responses for the
submitShipmentStatusUpdates
,getCustomerInvoices
,getCustomerInvoice
,getPackageSlips
, andgetPackageSlip
operations. Any successful call to one of these operations will always return the same static response for that operation.
- The Vendor Direct Fulfillment Transactions API 2021-12-28 version supports all of the equivalent V1 production operations.
Use the Vendor Direct Fulfillment SandboxData API 2021-10-28 version to generate fictional orders to use while testing with these APIs.
Testing using the supported Direct Fulfillment APIs
Here are the high level steps for testing using these APIs:
-
Generate fictional orders for testing. The orders that you generate are designed to accommodate the specific business test scenarios described under Scenarios.
-
After the orders are generated, use them to perform the business test scenarios with the supported Vendor Direct Fulfillment APIs and operations.
Important
You must direct your sandbox requests to the Selling Partner API sandbox endpoints. If you are using a SP-API sandbox environment to test a call that requires a Restricted Data Token (RDT), you must get the RDT from the production environment and pass it to your sandbox call. More information about restricted operations for which you will need an RDT can be found here.
Scenarios
The following business scenarios are supported in the generated orders for testing purposes. These are the only use cases supported by the test orders, and are focused primarily on label generation for shipping. Unless otherwise indicated, the label scenarios return a fixed, standardized, fictional label.
- LIFECYCLE: Use these test orders to simulate order life cycle testing. The response to an operation that employs these orders can vary. For example, a ship label request made for a multi-box order will result in a multiple label response. Similarly, a ship label request made with a package dimension change can result in a ship method change in the response.
- LABEL_CASE-SHIP_METHOD_UNASSIGNABLE: Use these test orders to simulate a ship method unassignable error, which will occur when Amazon is not able to assign a ship method for an order.
- LABEL_CASE-INCONSISTENT_METHODS: Use these test orders to simulate an "inconsistent ship method" error, which will occur when Amazon is not able to assign the same ship method to all of the boxes for a multi-box or multi-package order.
- LABEL_CASE-CARRIER_INTERNAL_FAILURE: Use these test orders to simulate a "carrier internal failure" error, which will occur when the carrier throws an error during label generation.
- LABEL_CASE-SYS_INTERNAL_FAILURE: Use these test orders to simulate a "system internal failure" error, which will occur when an unexpected failure happens in Amazon's systems.
- LABEL_CASE-DEST_ADDRESS_WRONG: Use these test orders to simulate a "destination address is wrong" error, which will happen when a customer address falls outside of a carrier's service area.
- LABEL_CASE-SERVICE_NOT_AVAILABLE: Use these test cases to simulate a "service not available" error, which will occur when the selected carrier service is not available or applicable.
- SHIP_CONFIRM_CASE-SHIP_METHOD_UNASSIGNABLE: Use these test orders to simulate a ship method unassignable error, which will occur when Amazon is not able to assign a ship method for an order. This applies to vendor own label shipments.
- SHIP_CONFIRM_CASE-SYS_INTERNAL_FAILURE: Use these test orders to simulate a "system internal failure" error, which will occur when an unexpected failure happens in Amazon's systems.
Test order ASINs
The generated fictional orders use the set of test ASINs (Amazon Standard Identification Numbers) and associated parcel characteristics shown in the following table.
Parcel type | ASIN | Package characteristics |
---|---|---|
small parcel | TESTASIN001 | Package dimensions (HxWxL): 1 in. x 1 in. x 2 in. Weight: 1 lb. |
small parcel | TESTASIN004 | Package Dimensions (HxWxL): 5 in. x 2 in. x 8 in. Weight: 3 lb. |
heavy-bulky | TESTASIN002 | Package Dimensions (HxWxL): 50 in. x 50 in. x 30 in. Weight: 100 lb. |
multi-piece | TESTASIN003 | Package1 Dimensions (HxWxL): 36 in. x 37 in. x 24 in. Weight: 7 lb. Package2 Dimensions (HxWxL): 10 in. x 30 in. x 40 in. Weight: 3 lb. |
Tutorial - Generating fictional orders for testing
Use this tutorial to generate test orders for the preceding scenarios for use when testing the Vendor Direct Fulfillment APIs.
Here are the high-level steps for generating test orders and related label scenarios:
-
Call the
generateOrderScenarios
operation, specifying the required party identifiers.Amazon receives the test data request. If the operation is successful, the response includes a
transactionId
value. Upon receiving a successful response, wait approximately 30-40 minutes before proceeding. -
Periodically call the
getOrderScenarios
operation, passing thetransactionId
value from the previous step, until you receive a successful response and thestatus
value in the response indicates that processing has ended. Processing will have ended when the status equals SUCCESS or FAILURE. At this point the response includes either the test orders if the status is SUCCESS, or an error array with details about the errors if the status is FAILURE.
Prerequisites
To complete this tutorial, you will need:
- Authorization from the selling partner for whom you are making calls.
- Approval for the Direct-to-Consumer Shipping role in your developer profile.
- The Direct-to-Consumer Shipping role selected in the App registration page for your application.
Step 1: Request fictional test orders
Request the test orders by providing the required party identifiers. To request generation of test orders, call the generateOrderScenarios
operation, passing the following parameters:
Request parameters
Request body
Parameter | Description | Required |
---|---|---|
orders |
An array of test orders as indicated by party identifiers. Type: < OrderScenarioRequest > array |
Yes |
Request example
POST http://sandbox.sellingpartnerapi-na.amazon.com//vendor/directFulfillment/
sandbox/2021-10-28/orders
{
"orders": [
{
"sellingParty": {
"partyId": "NIQQM"
},
"shipFromParty": {
"partyId": "CWPQ"
}
}
]
}
Response
A successful response includes the following:
Parameter | Description | Required |
---|---|---|
transactionId |
A GUID assigned by Amazon to identify this transaction. Type: string |
Yes |
Response example
{
"transactionId": "0343fcb3-fd7e-455e-968f-fb4ff7dd4081-20211014222021"
}
After receiving a successful response with the transactionId, wait approximately 30-40 minutes before proceeding to Step 2.
Step 2: Return the status and the requested fictional orders if ready
To retrieve the status of the generateOrderScenarios transaction, and the requested test order data if available, call the getOrderScenarios
operation and pass the required transactionId
parameter. You will want to periodically call this operation until you receive either a successful response that contains the generated test orders, or a failure response that contains an error array with details about the errors.
After you receive the test orders, use them to perform dynamic ship label testing with the supported Vendor Direct Fulfillment APIs and operations.
Request parameters
Path parameter
Parameter | Description | Required |
---|---|---|
transactionId |
The transaction identifier returned in the response to the generateOrderScenarios operation. | Yes |
Request example
GET http://sandbox.sellingpartnerapi-na.amazon.com/vendor/directFulfillment/
sandbox/2021-10-28/transactions/0343fcb3-fd7e-455e-968f-fb4ff7dd4081-20211014222021
Response
A successful response includes the following:
Parameter | Description | Required |
---|---|---|
transactionStatus |
The transaction details including the status. If the transaction was successful, also includes the requested test order data. Type: Transaction |
Yes |
Response example
Success (HTTP status code 200) - The response contains the generated scenario test data with order numbers
{
"transactionStatus":
{
"transactionId": "ff35f39e-e69f-499e-903e-6c4f6c32609f-20210827003315",
"status": "Success",
"testCaseData":
{
"scenarios": [
{
"scenarioId": "LIFECYCLE",
"orders": [
{
"orderId": "T1111N"
},
{
"orderId": "T1111P"
}
]
},
{
"scenarioId": "LABEL_CASE-SHIP_METHOD_UNASSIGNABLE",
"orders": [
{
"orderId": "T5555N"
},
{
"orderId": "T5555P"
}
]
},
{
"scenarioId": "LABEL_CASE-INCONSISTENT_METHODS",
"orders": [
{
"orderId": "T2222N"
},
{
"orderId": "T2222P"
}
]
},
{
"scenarioId": "LABEL_CASE-CARRIER_INTERNAL_FAILURE",
"orders": [
{
"orderId": "T3333N"
},
{
"orderId": "T3333P"
}
]
},
{
"scenarioId": "LABEL_CASE-SYS_INTERNAL_FAILURE",
"orders": [
{
"orderId": "T4444N"
},
{
"orderId": "T4444P"
}
]
},
{
"scenarioId": "SHIP_CONFIRM_CASE-SHIP_METHOD_UNASSIGNABLE",
"orders": [
{
"orderId": "buw38"
}
]
},
{
"scenarioId": "SHIP_CONFIRM_CASE-SYS_INTERNAL_FAILURE",
"orders": [
{
"orderId": "qqw52"
}
]
},
{
"scenarioId": "LABEL_CASE-DEST_ADDRESS_WRONG",
"orders": [
{
"orderId": "T6666N"
},
{
"orderId": "T6666P"
}
]
},
{
"scenarioId": "LABEL_CASE-SERVICE_NOT_AVAILABLE",
"orders": [
{
"orderId": "T7777N"
},
{
"orderId": "T7777P"
}
]
}
]
}
}
}
Response example
Processing (HTTP status code 404) - The request is processing and the generation of the test data is not yet complete.
{
"errors": [
{
"code": "ResourceNotFound",
"message": "Cannot find resource by the given URI"
}
]
}
Response example
Failure (HTTP status code 200) - The test data failed to generate. Refer to the errors array for more information.
{
"transactionStatus":
{
"transactionId": "ee8363d3-d061-4b17-b218-d3c80e014c2f-20220105231359",
"status": "FAILED",
"testCaseData":
{
"scenarios": [
{
"scenarioId": "",
"orders": []
}
]
},
"errors": [
{
"code": "INVALID_WAREHOUSE_CODE",
"details": "Invalid Warehouse Code. Retry request with correct Warehouse code"
}
]
}
}
Updated about 2 months ago