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 create and update inbound orders to ship inventory to AWD distribution centers, track inventory inside AWD distribution centers, and track shipments on the way to AWD distribution centers. For information about AWD API operations, data types, and schemas, refer to the Amazon Warehousing and Distribution API Reference.

📘
Note
This API is available in the US marketplace.

Key features

Create inbound orders: Verify AWD inbound eligibility and create inbound orders with a region preference.
Update inbound orders: Update one or more individual attributes for an inbound order, such as the packagesToInbound, originAddress, and preferences attributes.
Cancel inbound orders: Cancel an inbound order.
List all inbound shipments: Retrieve all inbound shipments across orders with optional filters.
Retrieve details about inbound shipments: Retrieve inbound shipments with optional filters and access shipment details with SKU-specific attributes.
Retrieve inbound shipment labels: Retrieve box labels for confirmed inbound shipments.
Update transport details: Update transport information for an AWD inbound shipment.
Track AWD inventory: Return real-time information, such as expiration dates, about the inventory within an AWD distribution center and units that are reserved by a replenishment order. Return quantity information for units that are in transit to AWD or from AWD to a Fulfillment by Amazon (FBA) facility.
Read interoperability: Access inbound orders that you create with Amazon's Send to Amazon Warehousing and Distribution UI.

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: Contains SKU-level quantities for all inventory in an AWD distribution center.

AWD inbound shipment workflow

The following diagram shows the steps to ship inventory to an AWD distribution center. This is an illustrative example and does not include all of the optional operations.

The AWD inbound shipment workflow.

Tutorial: Create an inbound order for shipment to AWD

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 1a. (Optional) - Determine if the packages that you specify are eligible for an AWD inbound order

Call the checkInboundEligibility operation and pass in the following parameters:

Body parameters

Name	Description	Required
Body	Represents the packages you want to inbound. Type: InboundPackages	Yes

Request example

POST https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundEligibility

{
  "packagesToInbound": [
    {
      "count": 1,
      "distributionPackage": {
        "contents": {
          "products": [
            {
              "quantity": 1,
              "sku": "SKU1",
              "attributes": [
                {
                  "name": "Color",
                  "value": "Blue"
                }
              ],
              "expiration": "2025-06-07T12:12:09.061Z",
              "prepDetails": {
                "prepCategory": "PERFORATED",
                "prepOwner": "AMAZON"
              }
            }
          ]
        },
        "measurements": {
          "dimensions": {
            "height": 28,
            "length": 27,
            "unitOfMeasurement": "CENTIMETERS",
            "width": 47
          },
          "weight": {
            "unitOfMeasurement": "KILOGRAMS",
            "weight": 7
          }
        },
        "type": "CASE"
      }
    }
  ]
}

Response

HTTP code	Description	Schema
200	The 200 response for `checkInboundEligibility`. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	InboundEligibility

Response example

{
  "ineligibilityReasons": [],
  "packagesToInbound": [
    {
      "ineligibilityReasons": [],
      "packageQuantity": {
        "count": 1,
        "distributionPackage": {
          "contents": {
            "packages": [],
            "products": [
              {
                "attributes": [
                  {
                    "name": "Color",
                    "value": "Blue"
                  }
                ],
                "expiration": "2025-06-07T12:12:09.061Z",
                "prepDetails": {
                  "prepCategory": "PERFORATED",
                  "prepInstructions": [],
                  "prepOwner": "AMAZON"
                },
                "quantity": 1,
                "sku": "SKU1"
              }
            ]
          },
          "measurements": {
            "dimensions": {
              "height": 28,
              "length": 27,
              "unitOfMeasurement": "CENTIMETERS",
              "width": 47
            },
            "weight": {
              "unitOfMeasurement": "KILOGRAMS",
              "weight": 7
            }
          },
          "type": "CASE"
        }
      },
      "status": "ELIGIBLE"
    }
  ],
  "previewedAt": "2025-01-02T20:31:13.836Z",
  "status": "ELIGIBLE"
}

Step 1. Create an AWD inbound order

Call the createInbound operation and pass in the following parameters (Amazon creates a single shipment per order):

Body parameters

Name	Description	Required
Body	Payload for creating an inbound order. Type: InboundOrderCreationData	Yes

The packagesToInbound must contain a list of packages that you want to inbound. ProductQuantity must include the MSKU, quantity, and party that prepares or labels the item. The SKU limit for an inbound order is 150 unique SKUs.

📘
Note
Each item that you ship must conform to Amazon's product packaging requirements. For more information, refer to Packaging and Prep Requirements in Seller Central Help. For more information about Amazon's product packaging requirements for your marketplace, refer to Seller Central URLs.

Request example

POST https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundOrders

{
  "externalReferenceId": "string",
  "originAddress": {
    "addressLine1": "string",
    "city": "string",
    "countryCode": "string",
    "name": "string",
    "postalCode": "string",
    "stateOrRegion": "string"
  },
  "packagesToInbound": [
    {
      "count": 1,
      "distributionPackage": {
        "contents": {
          "products": [
            {
              "quantity": 1,
              "sku": "SKU1",
              "attributes": [
                {
                  "name": "Color",
                  "value": "Blue"
                }
              ],
              "expiration": "2025-06-07T12:12:09.061Z",
              "prepDetails": {
                "prepCategory": "PERFORATED",
                "prepOwner": "AMAZON"
              }
            }
          ]
        },
        "measurements": {
          "dimensions": {
            "height": 28,
            "length": 27,
            "unitOfMeasurement": "CENTIMETERS",
            "width": 47
          },
          "weight": {
            "unitOfMeasurement": "KILOGRAMS",
            "weight": 7
          }
        },
        "type": "CASE"
      },
      "preferences": {
        "destinationRegion": "us-east"
      }
    }
  ]
}

Response

HTTP code	Description	Schema
201	`createInbound` 201 response. Headers : `Location` (string) : Location header with the order ID for the newly created inbound order. `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	InboundOrderReference

Response example

{
  "orderId": "STAR-TYAHS6NMDXXX"
}

📘
Note
Amazon does not support multiple expiration dates per SKU on a single inbound order. To send a SKU with multiple expiration dates to the AWD distribution center, you must create multiple inbound orders.

Step 2. Review the inbound order

To review the inbound order details and destination address, call the getInbound operation and pass in the following parameters.

Query parameters

Name	Description	Required
`orderId`	ID for the inbound order to be retrieved. Type: string	Yes

Request example

GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundOrders/STAR-TYAHS6NMDXXX

Response

HTTP code	Description	Schema
200	The 200 response for `getInbound`. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	InboundOrder

Response example

{
  "createdAt": "2024-11-23T01:09:14.624Z",
  "externalReferenceId": "string",
  "orderId": "STAR-TYAHS6NMDXXX",
  "orderStatus": "DRAFT",
  "originAddress": {
    "city": "string",
    "countryCode": "string",
    "district": "string",
    "name": "string",
    "postalCode": "string",
    "stateOrRegion": "string",
    "addressLine1": "string",
    "addressLine2": "string"
  },
  "packagesToInbound": [
    {
      "count": 1,
      "distributionPackage": {
        "contents": {
          "products": [
            {
              "quantity": 1,
              "sku": "SKU1",
              "attributes": [
                {
                  "name": "Color",
                  "value": "Blue"
                },
                {
                  "name": "asin",
                  "value": "B00OLPAXXX"
                },
                {
                  "name": "glProductGroupType",
                  "value": "gl_beauty"
                }
              ],
              "expiration": "2025-06-07T12:12:09.061Z",
              "prepDetails": {
                "prepCategory": "PERFORATED",
                "prepOwner": "AMAZON"
              }
            }
          ]
        },
        "measurements": {
          "dimensions": {
            "height": 28,
            "length": 27,
            "unitOfMeasurement": "CENTIMETERS",
            "width": 47
          },
          "weight": {
            "unitOfMeasurement": "KILOGRAMS",
            "weight": 7
          }
        },
        "type": "CASE"
      }
    }
  ],
  "updatedAt": "2024-11-23T01:09:14.624Z",
  "destinationDetails": [
    {
      "destinationAddress": {
        "countryCode": "string",
        "city": "string",
        "district": "string",
        "name": "string",
        "postalCode": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "addressLine3": "string",
        "stateOrRegion": "string"
      },
      "destinationRegion": "us-east"
    }
  ]
}

📘
Note
The inbound ShipmentId generates only upon confirmation of the inbound order.

Step 2b. Update the inbound order

The updateInbound operation updates the draft AWD inbound order for the packages that you want to inbound. You can only update AWD inbound orders in DRAFT status and that don't have seller confirmation.

📘
Note
When you update an inbound order, the system re-evaluates the order details. This re-evaluation process might result in the assignment of a different destination address for the inbound shipment.

Call the updateInbound operation and pass in the following parameters:

Path parameters

Name	Description	Required
`orderId`	The ID of the inbound order that you want to update. Type: string	Yes

Body parameters

Name	Description	Required
Body	Represents an AWD inbound order. Type: InboundOrder	Yes

Request example

PUT https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundOrders/STAR-TYAHS6NMDXXX

{
  "destinationDetails": {
    "destinationAddress": {
      "countryCode": "US",
      "city": "NORTH EAST",
      "district": "",
      "name": "IUSL",
      "postalCode": "21901-2914",
      "addressLine1": "600 PRINCIPIO PKWY W",
      "addressLine2": "",
      "addressLine3": "",
      "stateOrRegion": "MD"
    },
    "destinationRegion": "us-east"
  },
  "createdAt": "2024-11-23T01:09:14.624Z",
  "externalReferenceId": "string",
  "orderId": "STAR-TYAHS6NMDXXX",
  "orderStatus": "DRAFT",
  "originAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "addressLine3": "string",
    "city": "string",
    "countryCode": "string",
    "county": "string",
    "district": "string",
    "name": "string",
    "phoneNumber": "string",
    "postalCode": "string",
    "stateOrRegion": "string"
  },
  "packagesToInbound": [
    {
      "count": 1,
      "distributionPackage": {
        "contents": {
          "products": [
            {
              "quantity": 1,
              "sku": "SKU1",
              "attributes": [
                {
                  "name": "Color",
                  "value": "Blue"
                },
                {
                  "name": "asin",
                  "value": "B00OLPAXXX"
                },
                {
                  "name": "glProductGroupType",
                  "value": "gl_beauty"
                }
              ],
              "expiration": "2025-06-07T12:12:09.061Z",
              "prepDetails": {
                "prepCategory": "PERFORATED",
                "prepOwner": "AMAZON"
              }
            }
          ]
        },
        "measurements": {
          "dimensions": {
            "height": 28,
            "length": 27,
            "unitOfMeasurement": "CENTIMETERS",
            "width": 47
          },
          "weight": {
            "unitOfMeasurement": "KILOGRAMS",
            "weight": 7
          }
        },
        "type": "CASE"
      }
    }
  ],
  "updatedAt": "2024-11-24T01:09:14.624Z",
  "preferences": {
    "destinationRegion": "us-west"
  }
}

Response

HTTP code	Description	Schema
204	The 204 response for `updateInbound`. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	No content

⭐
Tip
After you update the inbound order, use the getInbound operation to review the inbound order details and confirm the destination address.

Step 3. Confirm the inbound order

With the confirmInbound operation, you can confirm an AWD inbound order in DRAFT status. This confirmation is a requirement for all transportation types and indicates that the order details are ready for further processing. After an order reaches CONFIRMED status, it advances in the inbound workflow and the next steps in the inbound shipping process begin.

Path parameters

Name	Description	Required
`orderId`	ID for the inbound order to confirm. Type: string	Yes

Request example

POST https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundOrders/STAR-TYAHS6NMDXXX/confirmation

Response

HTTP code	Description	Schema
204	The 204 response for `confirmInbound`. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	No content

Step 4. Generate the box labels

Call the getInboundShipmentLabels operation to request unique box labels for your inbound shipments. After you make the call, poll the system regularly to check for a GENERATED labelStatus. When the box labels are ready, affix each box label with its corresponding package in the shipment. The labels indicate the package contents and help the AWD distribution center process your shipment quickly and accurately.

Path parameters

Name	Description	Required
`orderId`	ID for the inbound order to confirm. Type: string	Yes

Query parameters

Name	Description	Required
`pageType`	Page type for the generated labels. The default is `PLAIN_PAPER`. Type: enum (PageType)	No
`formatType`	The format type of the output file that contains your labels. Type: enum (FormatType)	No

Request example

GET https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundShipments/STAR-X2QWMFFNK5XXX/labels

Response

HTTP code	Description	Schema
200	The 200 response for `getInboundShipmentLabels`. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	ShipmentLabels

Response example

{
   "labelDownloadURL": "https://amzn-storage-label-prod-prod-us-east-1.s3.amazonaws.com/47a864aa-a0be-44ea-89d2-397381130c6b.zip?response-content-disposition=attachment%3B%20filename%3D%22STAR-VX25NKF4PW654-package-labels.zip%22&X-Amz-Security-Token=IQoJb3JpZ2luX2VjECwaCXVzLWVhc3QtMSJGMEQCIE9RuRZwQW398KTgvo39o9FeIia7HNBC0q2eAYPksU97AiBBoheN0Nvgw5AR3mhbEUxOkYYf3O%2BAtCexv5QIbuJ%2B3yq2BAj0%2F%2F%2F%2F%2F%2F%2F%2F%2F%2F8BEAAaDDk2NTg2NDc1MjU0MSIMeIiMEu0VD1GiG5leKooEvb03OBNXHMUSvCgGqKagGewnBkqT6NR0CsxsxNVgCSu65f81liHOALq9UFlMYwETcNfjFqvfEcxGrwmsvNovQjoolT4Odw6x0PL4DrF0Z%2BikFPnEpXzqfoqV%2Bw3VoFzp2krDx5ozP4voXYLsx6TlnI5Ln0S0linHroDCocds7meaMPq7yyN9l6zMrDK9uelNTqwcVDP0gM20Fbk0bkN%2B%2B5TozA%2FG%2Bg24q7q2StjQD%2B1SyCbtTB81xx4B6txfMD05IwotrIUmUzK%2FTBCSCiJJoX7zZJaH2If2Sr4%2B3GL1Jecks3kgKFhIR4rsnKuv3qBSmujFS%2FPK5W9L6PcD2iwvkSUPskSgi8tb2eqrjUFP6Yj9amiHwHa6NoyJ%2Fa3LLwhu1B85BnPqhbDRsMwCz7xkXZwKwviFRZwzxBBSHWoJjou3CTR%2Fvz0ALWB9DvEjjMMqNUkkIJPddFi%2B%2F1Ok77k16rnWtTVxh9PHO33VpN4Z0L7hbC5N6nybTLE%2BzpozygOoL%2FHCz8XXLoYYbqArN0VwggqtNJOx%2BNZQEyeAf1qRhwRqSaT9LLuETzBK7lnafSuZjmaHot%2FC5dWe2e2l6XBrdvj%2F8LNjj2QiwB8K0jQ2T41VKVz984tprWQbkNF%2F823lbRxNZ9cw5cgk8M9oavUhXfIuFe07RTJ86ogyyDagyD86nbiDbG6jEhKCMMmt4LQGOqcBv%2BO7mc6nKzf%2BBan7Wwq8WEgYIu78%2BgdToX0RI3l%2FHHH9iTMAQju3c9zd8WfN2r0e8lgBCHdH%2B7C58vlgG4TBQnv2CPHQj47wBT0rktnjhNA4apChxpYXYYMAYWn%2BRPIZvXsjfYG%2FGpq%2FOMQ1d2Q%2B0lsNz19NXfnhWPWrmDyFAiLw3cIMYv7jeApuRLgsAmGHRLBiFRNgJvzX7pny819tbZH8QtFpdMc%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240717T214956Z&X-Amz-SignedHeaders=host&X-Amz-Credential=ASIA6BYQGQWOSQYAHZ2S%2F20240717%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Expires=600&X-Amz-Signature=8a49fdc8fde5975c01f71aa8cf5648180459ec4d99488fcf9fd6879d9af738ad",

   "labelStatus": "GENERATED"
}

📘
Note
The labels that you generate are valid for 600 seconds and are in a compressed .zip file format.

Step 5. Update the tracking information

You must update the tracking information after you send shipments to AWD distribution centers with non-partnered carriers. The updateInboundShipmentTransportDetails operation requires that you input the shipmentId and transportation information.

For small parcel shipments, you can provide only one booking ID. Amazon uses the booking ID to track and manage incoming inventory.

Call the updateInboundShipmentTransportDetails operation and pass in the following parameters:

Path parameters

Name	Description	Required
`shipmentId`	The shipment ID. Type: string	Yes

Body

Name	Description	Required
Body	Transportation details for the shipment. Type: TransportationDetails	Yes

Request example

PUT https://sellingpartnerapi-na.amazon.com/awd/2024-05-09/inboundShipments/STAR-X2QWMFFNK5XXX/transport

{
  "trackingDetails": [
    {
      "carrierCode": {
        "carrierCodeType": "SCAC"
      },
      "bookingId": "TRACK123456"
    }
  ]
}

Response

HTTP code	Description	Schema
204	The 204 response for `updateInboundShipmentTransportDetails`. Headers : `x-amzn-RateLimit-Limit` (string) : Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string) : Unique request reference identifier.	No content

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 `maxResults` 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 maxResults 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

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 `maxResults` 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 `maxResults` 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

shipments List of inbound shipment summaries.
Type: < InboundShipmentSummary > array

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 `maxResults` 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 details Defaults 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 `maxResults` 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

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 `maxResults` 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,
        "replenishmentQuantity": 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,
        "replenishmentQuantity": 100
      },
      "sku": "SKU2",
      "totalInboundQuantity": 50,
      "totalOnhandQuantity": 600
    }
  ],
  "nextToken": "eyJhdmFpbGFibGVRdWFudGl0eSI6MCwiY2hhbm5lbElkIjoiYWZuLXVzIiwic2t1VmFsdWUiOiJHQVRFV0FZX1RFU1RfU0tVXzMiLCJza3VUeXBlIjoiTVNLVSJ9"
}

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 `maxResults` 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

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 `maxResults` 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,
        "replenishmentQuantity": 50
      },
      "sku": "SKU_2",
      "totalInboundQuantity": 10,
      "totalOnhandQuantity": 200
    }
  ]
}

Resolve SKU preparation errors

If you encounter SKU preparation errors, use the checkInboundEligibility operation to verify the ineligibilityReasons. Use the following table to review the error codes and resolutions.

Error example

"ineligibilityReasons": [{
    "code": "EXPECTED_NON_NULL_LABEL_OWNER",
    "description": " Label owner must not be null for the SKU <SKU123> with prep category <PERFORATED>. Possible values are:[AMAZON/SELF]. For more details on prep guidance, refer https://sellercentral.amazon.com/help/hub/reference/external/GF4G7547KSLDX2KC"
}]

Error codes and resolutions

Error code	Resolution guidance	Resolution example
`EXPECTED_NON_NULL_LABEL_OWNER`	Add `labelOwner` as `AMAZON/SELF`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "AMAZON", "labelOwner": "SELF"}`
`EXPECTED_NON_NULL_PREP_OWNER`	Add `prepOwner` as `AMAZON/SELF`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "AMAZON", "labelOwner": "SELF"}`
`EXPECTED_SAME_PREP_LABEL_OWNERS`	Add `prepOwner` and `labelOwner` with the same values	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "AMAZON", "labelOwner": "AMAZON"}`
`EXPECTED_SELF_PREP_OWNER`	Add `prepOwner` as `SELF`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "SELF", "labelOwner": "AMAZON"}`
`EXPECTED_AMAZON_PREP_OWNER`	Add `prepOwner` as `AMAZON`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "AMAZON", "labelOwner": "SELF"}`
`EXPECTED_SELF_LABEL_OWNER`	Add `labelOwner` as `SELF`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "AMAZON", "labelOwner": "SELF"}`
`EXPECTED_AMAZON_LABEL_OWNER`	Add `labelOwner` as `AMAZON`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "SELF", "labelOwner": "AMAZON"}`
`EXPECTED_NULL_LABEL_OWNER`	Exclude `labelOwner`	`prepDetails: {"prepCategory": "PERFORATED", "prepOwner": "AMAZON"}`
`EXPECTED_NULL_PREP_OWNER`	Exclude `prepOwner`	`prepDetails: {"prepCategory": "PERFORATED", "labelOwner": "AMAZON"}`

Updated 1 day ago

What is the Amazon Warehousing and Distribution API?

📘Note

Key features

Terminology

AWD inbound shipment workflow

Tutorial: Create an inbound order for shipment to AWD

Prerequisites

Step 1a. (Optional) - Determine if the packages that you specify are eligible for an AWD inbound order

Body parameters

Request example

Response

Response example

Step 1. Create an AWD inbound order

Body parameters

📘Note

Request example

Response

Response example

📘Note

Step 2. Review the inbound order

Query parameters

Request example

Response

Response example

📘Note

Step 2b. Update the inbound order

📘Note

Path parameters

Body parameters

Request example

Response

⭐Tip

Step 3. Confirm the inbound order

Path parameters

Request example

Response

Step 4. Generate the box labels

Path parameters

Query parameters

Request example

Response

Response example

📘Note

Step 5. Update the tracking information

Path parameters

Body

Request example

Response

Tutorial: Retrieve a list of inbound shipments for a specific time

Prerequisites

Step 1. Get a list of all inbound orders

Query parameters

Request example

Response

Response example

Tutorial: Retrieve and filter a list of inbound shipments

Prerequisites

Step 1. Get a list of all inbound orders

Query parameters

Request example

Response

Response example

Tutorial: Track an inbound shipment with expected and received SKU details

Prerequisites

Step 1. Get inbound shipment details based on a shipmentId

Path parameters

Query parameters

Request example

Response

Response example

Tutorial: Get all available inventory summaries with detail

Prerequisites

Step 1. Get AWD inventory summaries

Query parameters

Request example

Response

Response example

Tutorial: Get inventory summaries for the seller specified SKUs

Prerequisites

Step 1. Get AWD inventory summaries

📘
Note

📘
Note

📘
Note

📘
Note

📘
Note

⭐
Tip

📘
Note