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?

The Selling Partner API for Amazon Warehousing and Distribution (AWD API) helps you to track inventory inside AWD distribution centers and track shipments going into AWD distribution centers. For details about API operations and associated data types and schemas, refer to the Amazon Warehousing and Distribution API reference.

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.
Track AWD inventory: Return detailed information 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, 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`	Token to retrieve the next set of paginated results. Type: string	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`	Token to retrieve the next set of paginated results. 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`	Token to retrieve the next set of paginated results. 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`	Token to retrieve the next set of paginated results. 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

Learn how to retrieve a particular AWD inbound shipment which contains items that are planned to be inbounded to a distribution center.

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": 1,
      "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"
            }
          ]
        },
        "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": 1,
        "unitOfMeasurement": "CASES"
      },
      "receivedQuantity": {
        "quantity": 1,
        "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`	Token to retrieve the next set of paginated results. 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`	Token to retrieve the next set of paginated results. Type: string

Response example

{
  "inventory": [
    {
      "inventoryDetails": {
        "availableDistributableQuantity": 300,
        "reservedDistributableQuantity": 300
      },
      "sku": "SKU_1",
      "totalInboundQuantity": 7,
      "totalOnhandQuantity": 600
    },
    {
      "inventoryDetails": {
        "availableDistributableQuantity": 200,
        "reservedDistributableQuantity": 0
      },
      "sku": "SKU_2",
      "totalInboundQuantity": 50,
      "totalOnhandQuantity": 200
    }
  ],
  "nextToken": "eyJh..."
}

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`	Token to retrieve the next set of paginated results. 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`	Token to retrieve the next set of paginated results. Type: string

Response example

{
  "inventory": [
    {
      "inventoryDetails": {
        "availableDistributableQuantity": 200,
        "reservedDistributableQuantity": 0
      },
      "sku": "SKU_2",
      "totalInboundQuantity": 10,
      "totalOnhandQuantity": 200
    }
  ]
}

Updated 3 days ago