HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

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:

Step 1. Get a list of all inbound orders

Call the listInboundShipments operation by passing the following parameters:

Query parameters

NameDescriptionRequired
sortByField to sort results by. Required if sortOrder is provided.
Type: enum (SortBy)
No
sortOrderSort the response in ASCENDING or DESCENDING order.
Type: enum (SortOrder)
No
shipmentStatusFilter by inbound shipment status.
Type: enum (InboundShipmentStatus)
No
updatedAfterList the inbound shipments that were updated after a certain time (inclusive). The date must be in ISO 8601 format.
Type: string (date-time)
No
updatedBeforeList the inbound shipments that were updated before a certain time (inclusive). The date must be in ISO 8601 format.
Type: string (date-time)
No
maxResultsMaximum number of results to return.
Minimum: 1
Maximum: 200
Type: integer (int32)
No
nextTokenA 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

NameDescription
nextTokenA 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
shipmentsList 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:

Step 1. Get a list of all inbound orders

Call the listInboundShipments operation by passing the following parameters:

Query parameters

NameDescriptionRequired
sortByField to sort results by. Required if sortOrder is provided.
Type: enum (SortBy)
No
sortOrderSort the response in ASCENDING or DESCENDING order.
Type: enum (SortOrder)
No
shipmentStatusFilter by inbound shipment status.
Type: enum (InboundShipmentStatus)
No
updatedAfterList the inbound shipments that were updated after a certain time (inclusive). The date must be in ISO 8601 format.
Type: string (date-time)
No
updatedBeforeList the inbound shipments that were updated before a certain time (inclusive). The date must be in ISO 8601 format.
Type: string (date-time)
No
maxResultsMaximum number of results to return.
Minimum: 1
Maximum: 200
Type: integer (int32)
No
nextTokenA 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

NameDescription
nextTokenA 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
shipmentsList 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:

Step 1. Get inbound shipment details based on a shipmentId

Call the getInboundShipment operation by passing the following parameters:

Path parameters

NameDescriptionRequired
shipmentIdUnique shipment ID.
Type: string
Yes

Query parameters

NameDescriptionRequired
skuQuantitiesSet 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

NameDescription
carrierCodeThe shipment carrier code.
Type: CarrierCode
createdAtTimestamp when the shipment was created. The date is returned in ISO 8601 format.
Type: string (date-time)
destinationAddressDestination address for this shipment.
Type: Address
externalReferenceIdClient-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
orderIdThe AWD inbound order ID that this inbound shipment belongs to.
minLength: 1
Type: string
originAddressOrigin address for this shipment. Type: Address
receivedQuantityQuantity received (at the receiving end) as part of this shipment.
Type: < InventoryQuantity > array
shipByTimestamp when the shipment is shipped.
Type: string (date-time)
shipmentContainerQuantitiesPackages that are part of this shipment.
Type: < DistributionPackageQuantity > array
shipmentIdUnique shipment ID. Type: string
shipmentStatusCurrent status of this shipment.
Type: enum (InboundShipmentStatus)
trackingIdCarrier-unique tracking ID for this shipment.
minLength : 1
Type: string
updatedAtTimestamp when the shipment was updated. The date is returned in ISO 8601 format.
Type: string (date-time)
warehouseReferenceIdAn AWD-provided reference ID that you can use to interact with the warehouse. For example, a carrier appointment booking.
Type: string
shipmentSkuQuantitiesQuantity 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:

Step 1. Get AWD inventory summaries

Call the listInventory operation by passing the following parameters:

Query parameters

NameDescriptionRequired
skuFilter by seller SKU for the item.
Type: string
No
sortOrderSort the response in ASCENDING or DESCENDING order.
Type: enum (SortOrder)
No
detailsSet to SHOW to return summaries with additional inventory details. Defaults to HIDE, which returns only inventory summary totals.
Type: enum (Details)
No
maxResultsMaximum number of results to return.
Minimum: 1
Maximum: 200
Type: integer (int32)
No
nextTokenA 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

NameDescription
inventoryList of inventory summaries. Type: < InventorySummary > array
nextTokenA 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:

Step 1. Get AWD inventory summaries

Call the listInventory operation by passing the following parameters:

Query parameters

NameDescriptionRequired
skuFilter by seller SKU for the item.
Type: string
No
sortOrderSort the response in ASCENDING or DESCENDING order.
Type: enum (SortOrder)
No
detailsSet to SHOW to return summaries with additional inventory details. Defaults to HIDE, which returns only inventory summary totals.
Type: enum (Details)
No
maxResultsMaximum number of results to return.
Minimum: 1
Maximum: 200
Type: integer (int32)
No
nextTokenA 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

NameDescription
inventoryList of inventory summaries. Type: < InventorySummary > array
nextTokenA 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
    }
  ]
}