Amazon Warehousing and Distribution API Use Case Guide
How to work with Amazon Warehousing and Distribution (AWD) orders using the Amazon Warehousing and Distribution API.
API Version: 2024-05-09
What is the Amazon Warehousing and Distribution API?
You can use the Amazon Warehousing and Distribution (AWD) API to track inventory for and shipments into AWD distribution centers. For information about API operations and associated data types and schemas, refer to the Amazon Warehousing and Distribution API reference.
Note
This API is available in the US marketplace.
Key features
- List all inbound shipments: Retrieve all inbound shipments across orders with optional filters.
- Retrieve details about inbound shipments: Return detailed information about an existing shipment, including expiration dates and preparation details for each SKU.
- Track AWD inventory: Return detailed information, such as expiration dates, about the real-time inventory status of units stored in an AWD distribution center and units that are reserved by a replenishment order.
- Interoperability: Access inbound orders created with Amazon's Send to Amazon Warehousing and Distribution UI with the AWD API.
Terminology
- Inbound order: Inbound orders instruct the movement of inventory from an arbitrary location to an AWD distribution center. An inbound order has one or more inbound shipments. Each inbound shipment represents a trackable movement provided by an underlying transportation carrier.
- Inbound shipments: Inbound shipments include a list of items that are contained within the shipment, and other details, such as: tracking number, carrier information, quantities received, expiration dates, preparation details, and your item label preparation preferences.
- Inventory listing: An inventory listing contains SKU-level quantities for all inventory in an AWD distribution center. You can retrieve quantitative information about inventory that can be replenished to a downstream channel and inventory reserved by a replenishment order.
Tutorial: Retrieve a list of inbound shipments for a specific time
Learn how to get a list of AWD inbound orders for a specific date-time.
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 Warehousing and Distribution role assigned to your developer profile.
- The Amazon Warehousing and Distribution role selected in the app registration page for your application.
Step 1. Get a list of all inbound orders
Call the listInboundShipments operation by passing the following parameters:
Query parameters
| Name | Description | Required |
|---|---|---|
sortBy | Field to sort results by. Required if sortOrder is provided. Type: enum ( SortBy) | No |
sortOrder | Sort the response in ASCENDING or DESCENDING order. Type: enum ( SortOrder) | No |
shipmentStatus | Filter by inbound shipment status. Type: enum ( InboundShipmentStatus) | No |
updatedAfter | List the inbound shipments that were updated after a certain time (inclusive). The date must be in ISO 8601 format. Type: string (date-time) | No |
updatedBefore | List the inbound shipments that were updated before a certain time (inclusive). The date must be in ISO 8601 format. Type: string (date-time) | No |
maxResults | Maximum number of results to return. Minimum: 1 Maximum: 200 Type: integer (int32) | No |
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string Default: 25 | No |
Request example
GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundShipments?sortBy=UPDATED_AT&sortOrder=ASCENDING&updatedAfter=2022-12-25T15:45:03.33Z&updatedBefore=2022-12-28T15:45:03.33Z&maxResults=5
Response
| Name | Description |
|---|---|
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string |
shipments | List of inbound shipment summaries. Type: < InboundShipmentSummary > array |
Response example
{
"nextToken": "eyJh...",
"shipments": [
{
"createdAt": "2024-03-06T21:51:53.983Z",
"externalReferenceId": "wf976707c6-6692-4e0a-b108-a1ba917a5cxx",
"orderId": "STAR-W2W4UMHYH6GXX",
"shipmentId": "STAR-RXMJTXWZGU2XX",
"shipmentStatus": "CLOSED",
"updatedAt": "2024-06-04T21:51:55.014Z"
},
{
"createdAt": "2024-03-06T21:17:26.945Z",
"externalReferenceId": "wf885a8eb0-4c20-455b-8687-ffc0eb8507xx",
"orderId": "STAR-QB6Y5BPDNXWXX",
"shipmentId": "STAR-WVEKXEGFHYFXX",
"shipmentStatus": "CLOSED",
"updatedAt": "2024-06-04T21:17:28.020Z"
},
{
"createdAt": "2024-06-04T20:48:46.752Z",
"externalReferenceId": "wfcc55fa04-d090-4b04-a110-a72f74dd82xx",
"orderId": "STAR-R4ZEGJFGWHXXX",
"shipmentId": "STAR-S7YJSYJXSXPXX",
"shipmentStatus": "CANCELLED",
"updatedAt": "2024-06-04T20:49:25.923Z"
},
{
"createdAt": "2024-06-04T20:46:40.866Z",
"externalReferenceId": "wf68f20503-043a-4f9f-b500-d59e257590xx",
"orderId": "STAR-UXBRMX4ENAZXX",
"shipmentId": "STAR-RADCKNCM2XYXX",
"shipmentStatus": "CANCELLED",
"updatedAt": "2024-06-04T20:47:18.686Z"
},
{
"createdAt": "2024-06-04T20:34:15.359Z",
"externalReferenceId": "wf46986b76-5575-467f-84d1-427fd80a78xx",
"orderId": "STAR-VFWFC2WZX6EXX",
"shipmentId": "STAR-TDVYDJMW52YXX",
"shipmentStatus": "CANCELLED",
"updatedAt": "2024-06-04T20:34:50.005Z"
}
]
}
Tutorial: Retrieve and filter a list of inbound shipments
Learn how to use shipmentStatus to filter the list of AWD inbound orders.
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 Warehousing and Distribution role assigned to your developer profile.
- The Amazon Warehousing and Distribution role selected in the app registration page for your application.
Step 1. Get a list of all inbound orders
Call the listInboundShipments operation by passing the following parameters:
Query parameters
| Name | Description | Required |
|---|---|---|
sortBy | Field to sort results by. Required if sortOrder is provided. Type: enum ( SortBy) | No |
sortOrder | Sort the response in ASCENDING or DESCENDING order. Type: enum ( SortOrder) | No |
shipmentStatus | Filter by inbound shipment status. Type: enum ( InboundShipmentStatus) | No |
updatedAfter | List the inbound shipments that were updated after a certain time (inclusive). The date must be in ISO 8601 format. Type: string (date-time) | No |
updatedBefore | List the inbound shipments that were updated before a certain time (inclusive). The date must be in ISO 8601 format. Type: string (date-time) | No |
maxResults | Maximum number of results to return. Minimum: 1 Maximum: 200 Type: integer (int32) | No |
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string | No |
Request example
GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundShipments?sortBy=UPDATED_AT&sortOrder=ASCENDING&shipmentStatus=CREATED&maxResults=5
Response
| Name | Description |
|---|---|
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string |
shipments | List of inbound shipment summaries. Type: < InboundShipmentSummary > array |
Response example
{
"nextToken": "eyJh...",
"shipments": [
{
"createdAt": "2024-06-04T18:42:40.262Z",
"externalReferenceId": "wf0d65f26a-0e30-46b1-8633-b75ebf832cyy",
"orderId": "STAR-SDKNUYRRSRKYY",
"shipmentId": "STAR-UWQJPM3BERJYY",
"shipmentStatus": "CREATED",
"updatedAt": "2024-06-04T18:43:13.251Z"
},
{
"createdAt": "2024-06-04T05:38:52.343Z",
"externalReferenceId": "wf6b9e237b-c898-4961-9891-5507a2d4ddyy",
"orderId": "STAR-V4PH26YS5FTYY",
"shipmentId": "STAR-XMAX23B44SPYY",
"shipmentStatus": "CREATED",
"updatedAt": "2024-06-04T05:39:24.750Z"
},
{
"createdAt": "2024-06-04T05:32:38.387Z",
"externalReferenceId": "wfb1402c90-3089-44ca-9f2c-35d056436cyy",
"orderId": "STAR-W3B5KXMWWPXYY",
"shipmentId": "STAR-XQR3Q3BENW5YY",
"shipmentStatus": "CREATED",
"updatedAt": "2024-06-04T05:33:39.022Z"
},
{
"createdAt": "2024-06-03T18:18:35.278Z",
"externalReferenceId": "wfb45e0961-4ae9-43f9-9516-43e1ad98b0yy",
"orderId": "STAR-RGKE7NYCPKWYY",
"shipmentId": "STAR-TWPBZWMM2XWYY",
"shipmentStatus": "CREATED",
"updatedAt": "2024-06-03T18:19:05.389Z"
},
{
"createdAt": "2024-06-03T14:48:15.235Z",
"externalReferenceId": "wf4872e1d6-ad5e-4989-97f5-41cdae9f63yy",
"orderId": "STAR-SRGD7GVD6GUYY",
"shipmentId": "STAR-QDDTWGJQSABYY",
"shipmentStatus": "CREATED",
"updatedAt": "2024-06-03T14:48:50.865Z"
}
]
}
Tutorial: Track an inbound shipment with expected and received SKU details
Learn how to retrieve a particular AWD inbound shipment which contains items that are planned to be inbounded to a distribution center. For each SKU, you can also retrieve expiration dates and prep details.
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 Warehousing and Distribution role assigned to your developer profile.
- The Amazon Warehousing and Distribution role selected in the app registration page for your application.
Step 1. Get inbound shipment details based on a shipmentId
Call the getInboundShipment operation by passing the following parameters:
Path parameters
| Name | Description | Required |
|---|---|---|
shipmentId | Unique shipment ID. Type: string | Yes |
Query parameters
| Name | Description | Required |
|---|---|---|
skuQuantities | Set SHOW to include the shipment SKU quantity detailsDefaults to HIDE which returns shipment without SKU quantities. Type: enum ( SkuQuantities) | No |
Request example
GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundShipments/STAR-RT6G6UWYQ4SDX?skuQuantities=SHOW
Response
| Name | Description |
|---|---|
carrierCode | The shipment carrier code. Type: CarrierCode |
createdAt | Timestamp when the shipment was created. The date is returned in ISO 8601 format. Type: string (date-time) |
destinationAddress | Destination address for this shipment. Type: Address |
externalReferenceId | Client-provided reference ID that can correlate this shipment to client resources. For example, to map this shipment to an internal bookkeeping order record. Type: string |
orderId | The AWD inbound order ID that this inbound shipment belongs to. minLength: 1 Type: string |
originAddress | Origin address for this shipment. Type: Address |
receivedQuantity | Quantity received (at the receiving end) as part of this shipment. Type: < InventoryQuantity > array |
shipBy | Timestamp when the shipment is shipped. Type: string (date-time) |
shipmentContainerQuantities | Packages that are part of this shipment. Type: < DistributionPackageQuantity > array |
shipmentId | Unique shipment ID. Type: string |
shipmentStatus | Current status of this shipment. Type: enum ( InboundShipmentStatus) |
trackingId | Carrier-unique tracking ID for this shipment. minLength : 1 Type: string |
updatedAt | Timestamp when the shipment was updated. The date is returned in ISO 8601 format. Type: string (date-time) |
warehouseReferenceId | An AWD-provided reference ID that you can use to interact with the warehouse. For example, a carrier appointment booking. Type: string |
shipmentSkuQuantities | Quantity details at SKU level for the shipment. This attribute only appears if the skuQuantities parameter in the request is set to SHOW.Type: < SkuQuantity > array |
Response example
{
"createdAt": "2023-07-27T12:23:49.324Z",
"destinationAddress": {
"addressLine1": "string",
"addressLine2": "string",
"addressLine3": "string",
"city": "string",
"countryCode": "string",
"district": "string",
"name": "string",
"postalCode": "string",
"stateOrRegion": "string"
},
"orderId": "STAR-SKFFWD6G6FMXX",
"originAddress": {
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "string",
"district": "string",
"name": "string",
"postalCode": "string",
"stateOrRegion": "string"
},
"receivedQuantity": [
{
"quantity": 0,
"unitOfMeasurement": "CASES"
}
],
"shipBy": "2024-06-30T18:29:59.000Z",
"shipmentContainerQuantities": [
{
"count": 2,
"distributionPackage": {
"contents": {
"packages": [],
"products": [
{
"attributes": [
{
"name": "asin",
"value": "B001CRVUXX"
},
{
"name": "glProductGroupType",
"value": "gl_office_product"
}
],
"quantity": 3,
"sku": "SKU1",
"expiration": "2025-06-07T12:12:09.061Z",
"prepDetails": {
"prepCategory": "PERFORATED",
"prepOwner": "AMAZON",
"labelOwner": "SELF",
"prepInstructions": [{
"prepType": "ITEM_POLYBAGGING",
"prepOwner": "AMAZON"
}]
}
}
]
},
"measurements": {
"dimensions": {
"height": 5.08,
"length": 25.4,
"unitOfMeasurement": "CENTIMETERS",
"width": 12.7
},
"weight": {
"unitOfMeasurement": "KILOGRAMS",
"weight": 9.07184
}
},
"type": "CASE"
}
}
],
"shipmentId": "STAR-RT6G6UWYQ4SXX",
"shipmentStatus": "CREATED",
"updatedAt": "2024-06-04T18:43:13.251Z",
"warehouseReferenceId": "5MEK9YYY",
"shipmentSkuQuantities": [
{
"expectedQuantity": {
"quantity": 2,
"unitOfMeasurement": "CASES"
},
"receivedQuantity": {
"quantity": 0,
"unitOfMeasurement": "CASES"
},
"sku": "SKU1"
}
]
}
Tutorial: Get all available inventory summaries with detail
Learn how to use the AWD Inventory API to return all the inventory summaries with detail.
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 Warehousing and Distribution role assigned to your developer profile.
- The Amazon Warehousing and Distribution role selected in the app registration page for your application.
Step 1. Get AWD inventory summaries
Call the listInventory operation by passing the following parameters:
Query parameters
| Name | Description | Required |
|---|---|---|
sku | Filter by seller SKU for the item. Type: string | No |
sortOrder | Sort the response in ASCENDING or DESCENDING order. Type: enum ( SortOrder) | No |
details | Set to SHOW to return summaries with additional inventory details. Defaults to HIDE, which returns only inventory summary totals. Type: enum ( Details) | No |
maxResults | Maximum number of results to return. Minimum: 1 Maximum: 200 Type: integer (int32) | No |
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string | No |
Request example
GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inventory?details=SHOW
Response
| Name | Description |
|---|---|
inventory | List of inventory summaries. Type: < InventorySummary > array |
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string |
Response example
{
"inventory": [
{
"inventoryDetails": {
"availableDistributableQuantity": 20,
"reservedDistributableQuantity": 10
},
"expirationDetails": [
{
"onhandQuantity": 10,
"expiration": "2025-09-12T00:00:00.061Z"
},
{
"onhandQuantity": 20,
"expiration": "2025-10-10T00:00:00.061Z"
}
],
"sku": "EDP-SKU1",
"totalInboundQuantity": 0,
"totalOnhandQuantity": 30
},
{
"inventoryDetails": {
"availableDistributableQuantity": 300,
"reservedDistributableQuantity": 300
},
"sku": "SKU2",
"totalInboundQuantity": 50,
"totalOnhandQuantity": 600
}
]
}
Tutorial: Get inventory summaries for the seller specified SKUs
Learn how to use the AWD Inventory API to return the inventory summaries for a particular SKU.
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 Warehousing and Distribution role assigned to your developer profile.
- The Amazon Warehousing and Distribution role selected in the app registration page for your application.
Step 1. Get AWD inventory summaries
Call the listInventory operation by passing the following parameters:
Query parameters
| Name | Description | Required |
|---|---|---|
sku | Filter by seller SKU for the item. Type: string | No |
sortOrder | Sort the response in ASCENDING or DESCENDING order. Type: enum ( SortOrder) | No |
details | Set to SHOW to return summaries with additional inventory details. Defaults to HIDE, which returns only inventory summary totals. Type: enum ( Details) | No |
maxResults | Maximum number of results to return. Minimum: 1 Maximum: 200 Type: integer (int32) | No |
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string | No |
Request example
GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inventory?sku=SKU_2&details=SHOW
Response
| Name | Description |
|---|---|
inventory | List of inventory summaries. Type: < InventorySummary > array |
nextToken | A token that is used to retrieve the next page of results. The response includes nextToken when the number of results exceeds the specified pageSize value. To get the next page of results, call the operation with this token and include the same arguments as the call that produced the token. To get a complete list, call this operation until nextToken is null. Note that this operation can return empty pages. Type: string |
Response example
{
"inventory": [
{
"inventoryDetails": {
"availableDistributableQuantity": 200,
"reservedDistributableQuantity": 0
},
"sku": "SKU_2",
"totalInboundQuantity": 10,
"totalOnhandQuantity": 200
}
]
}
Updated 11 days ago