Amazon Warehousing and Distribution API v2024-05-09 Reference

Retrieve and track AWD inbound shipments that contain items that are inbound to a distribution center.

The Selling Partner API for Amazon Warehousing and Distribution (AWD) provides programmatic access to information about AWD shipments and inventory.

Version information

Version : 2024-05-09

Contact information

Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html

License information

License : Apache License 2.0
License URL : https://www.apache.org/licenses/LICENSE-2.0

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

application/json

Produces

application/json

Operations

getInboundShipment
listInboundShipments
listInventory

Paths

GET /awd/2024-05-09/inboundShipments/{shipmentId}

Operation: getInboundShipment

Description

Retrieves an AWD inbound shipment.

Usage Plan:

Rate (requests per second)	Burst
2	2

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API

Parameters

Type	Name	Description	Schema
Path	shipmentId required	ID for the shipment. A shipment contains the cases being inbounded. minLength : 1	string
Query	skuQuantities optional	If equal to `SHOW`, the response includes the shipment SKU quantity details. Defaults to `HIDE`, in which case the response does not contain SKU quantities	enum (SkuQuantities)

Responses

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

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

GET /awd/2024-05-09/inboundShipments

Operation: listInboundShipments

Description

Retrieves a summary of all the inbound AWD shipments associated with a merchant, with the ability to apply optional filters.

Usage Plan:

Rate (requests per second)	Burst
1	1

Parameters

Type	Name	Description	Schema	Default
Query	sortBy optional	Field to sort results by. By default, the response will be sorted by UPDATED_AT.	enum (SortBy)	-
Query	sortOrder optional	Sort the response in ASCENDING or DESCENDING order. By default, the response will be sorted in DESCENDING order.	enum (SortOrder)	-
Query	shipmentStatus optional	Filter by inbound shipment status.	enum (ShipmentStatus)	-
Query	updatedAfter optional	List the inbound shipments that were updated after a certain time (inclusive). The date must be in ISO 8601 format.	string (date-time)	-
Query	updatedBefore optional	List the inbound shipments that were updated before a certain time (inclusive). The date must be in ISO 8601 format.	string (date-time)	-
Query	maxResults optional	Maximum number of results to return. Minimum : 1 Maximum : 200	integer (int32)	`25`
Query	nextToken optional	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.	string	-

Responses

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

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

GET /awd/2024-05-09/inventory

Operation: listInventory

Description

Lists AWD inventory associated with a merchant with the ability to apply optional filters.

Usage Plan:

Rate (requests per second)	Burst
2	2

Parameters

Type	Name	Description	Schema	Default
Query	sku optional	Filter by seller or merchant SKU for the item.	string	-
Query	sortOrder optional	Sort the response in `ASCENDING` or `DESCENDING` order.	enum (SortOrder)	-
Query	details optional	Set to `SHOW` to return summaries with additional inventory details. Defaults to `HIDE,` which returns only inventory summary totals.	enum (Details)	-
Query	nextToken optional	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.	string	-
Query	maxResults optional	Maximum number of results to return. Minimum : 1 Maximum : 200	integer (int32)	`25`

Responses

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

For error status codes, descriptions and schemas, see Error responses and schemas.

Produces

application/json

Error Responses and Schemas

This table contains HTTP status codes and associated information for error responses.

HTTP Code	Description	Schema
400	Request has missing or invalid parameters and cannot be parsed. Headers: `x-amzn-RateLimit-Limit` (string):Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
403	Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
404	The resource specified does not exist. Headers: `x-amzn-RateLimit-Limit` (string):Your rate limit (requests per second) for this operation. `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
413	The request size exceeded the maximum accepted size. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
415	The request payload is in an unsupported format. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
429	The frequency of requests was greater than allowed. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
500	An unexpected condition occurred that prevented the server from fulfilling the request. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList
503	Temporary overloading or maintenance of the server. Headers: `x-amzn-RequestId` (string):Unique request reference identifier.	ErrorList

Definitions

Address

Shipping address that represents the origin or destination location.

Name	Description	Schema
addressLine1 required	First line of the address text.	string
addressLine2 optional	Optional second line of the address text.	string
addressLine3 optional	Optional third line of the address text.	string
city optional	Optional city where this address is located.	string
countryCode required	Two-digit, ISO 3166-1 alpha-2 formatted country code where this address is located.	string
county optional	Optional county where this address is located. Example : `"Washington"`	string
district optional	Optional district where this address is located.	string
name required	Name of the person, business, or institution at this address.	string
phoneNumber optional	Optional E.164-formatted phone number for an available contact at this address. Example : `"+14155552671"`	string
postalCode optional	Optional postal code where this address is located.	string
stateOrRegion required	State or region where this address is located. Note that this is contextual to the specified country code.	string

CarrierCode

Identifies the carrier that will deliver the shipment.

Name	Description	Schema
carrierCodeType optional	Denotes the carrier type.	CarrierCodeType
carrierCodeValue optional	Value of the carrier code. Example : `"TestCarrierCode"`	string

CarrierCodeType

Denotes the type for the carrier.

Type : enum

Value	Description
SCAC	Standard Carrier Alpha Code. Refer to What is a Standard Carrier Alpha Code for more information.

DimensionUnitOfMeasurement

Unit of measurement for package dimensions.

Type : enum

Value	Description
INCHES	Denotes package dimensions in inches.
CENTIMETERS	Denotes package dimensions in centimeters.

DistributionPackage

Represents an AWD distribution package.

Name	Description	Schema
contents required	The contents appropriate for the type.	DistributionPackageContents
measurements required	Measurements of a package, including weight, volume, and dimensions.	MeasurementData
type required	Type of distribution package.	DistributionPackageType

DistributionPackageContents

Represents the contents inside a package, which can be products or a nested package.

Name	Description	Schema
packages optional	This is required only when `DistributionPackageType=PALLET`.	< DistributionPackageQuantity > array
products optional	This is required only when `DistributionPackageType=CASE`.	< ProductQuantity > array

DistributionPackageQuantity

Represents a distribution package with its respective quantity.

Name	Description	Schema
count required	Number of cases or pallets with the same package configuration.	integer (int32)
distributionPackage required	Represents an AWD distribution package.	DistributionPackage

DistributionPackageType

Type of distribution packages.

Type : enum

Value	Description
CASE	Package type `CASE`.
PALLET	Package type `PALLET`. Currently, the `PALLET` package type is not supported.

Error

Error response returned when the request is unsuccessful.

Name	Description	Schema
code required	An error code that identifies the type of error that occurred.	string
details optional	Additional details that can help the caller understand or fix the issue.	string
message required	A message that describes the error condition.	string

ErrorList

This exception is thrown when client inputs are invalid.

Name	Description	Schema
errors required	A list of errors describing the failures.	< Error > array

InboundShipment

Represents an AWD inbound shipment.

Name	Description	Schema
carrierCode optional	The shipment carrier code.	CarrierCode
createdAt optional	Timestamp when the shipment was created. The date is returned in ISO 8601 format.	string (date-time)
destinationAddress required	Destination address for this shipment.	Address
externalReferenceId optional	Client-provided reference ID that can correlate this shipment to client resources. For example, to map this shipment to an internal bookkeeping order record. Example : `"TestReferenceId"`	string
orderId required	The AWD inbound order ID that this inbound shipment belongs to. minLength : 1	string
originAddress required	Origin address for this shipment.	Address
receivedQuantity optional	Quantity received (at the receiving end) as part of this shipment.	< InventoryQuantity > array
shipBy optional	Timestamp when the shipment will be shipped.	string (date-time)
shipmentContainerQuantities required	Packages that are part of this shipment.	< DistributionPackageQuantity > array
shipmentId required	Unique shipment ID. minLength : 1	string
shipmentSkuQuantities optional	Quantity details at SKU level for the shipment. This attribute will only appear if the skuQuantities parameter in the request is set to SHOW.	< SkuQuantity > array
destinationRegion optional	Assigned region where the order will be shipped. This can differ from what was passed as preference. AWD currently supports following region IDs: [us-west, us-east] Example : `"us-west"`	string
shipmentStatus required	Current status of this shipment.	InboundShipmentStatus
trackingId optional	Carrier-unique tracking ID for this shipment. minLength : 1	string
updatedAt optional	Timestamp when the shipment was updated. The date is returned in ISO 8601 format.	string (date-time)
warehouseReferenceId optional	An AWD-provided reference ID that you can use to interact with the warehouse. For example, a carrier appointment booking. Example : `"TestWarehouseReferenceId"`	string

InboundShipmentStatus

Possible shipment statuses used by shipments.

Type : enum

Value	Description
CREATED	Shipment is created but has not yet shipped.
SHIPPED	Shipment was picked up by the carrier or was dropped off with the carrier.
IN_TRANSIT	The carrier has notified AWD that the shipment is in transit between origin and destination node.
RECEIVING	The shipment has been partially received.
DELIVERED	The shipment has reached the destination node and has been delivered to the facility yard. The shipment receive process at the warehouse will start soon.
CLOSED	No more actions required on the shipment. This is a final state.
CANCELLED	Shipment has been cancelled. This is a final state.

InboundShipmentSummary

Summary for an AWD inbound shipment containing the shipment ID, which can be used to retrieve the actual shipment.

Name	Description	Schema
createdAt optional	Timestamp when the shipment was created.	string (date-time)
externalReferenceId optional	Optional client-provided reference ID that can be used to correlate this shipment with client resources. For example, to map this shipment to an internal bookkeeping order record. Example : `"TestReferenceId"`	string
orderId required	The AWD inbound order ID that this inbound shipment belongs to. minLength : 1	string
shipmentId required	A unique shipment ID. minLength : 1	string
shipmentStatus required	Possible shipment statuses used by shipments.	InboundShipmentStatus
updatedAt optional	Timestamp when the shipment was updated.	string (date-time)

ExpirationDetails

The expiration details of the inventory. This object will only appear if the details parameter in the request is set to SHOW.

Name	Description	Schema
expiration optional	The expiration date of the SKU.	string (date-time)
onhandQuantity optional	The quantity that is present in AWD.	integer (int64)

InventoryDetails

Additional inventory details. This object is only displayed if the details parameter in the request is set to SHOW.

Name	Description	Schema
availableDistributableQuantity optional	Quantity that is available for downstream channel replenishment.	integer (int64)
reservedDistributableQuantity optional	Quantity that is reserved for a downstream channel replenishment order that is being prepared for shipment.	integer (int64)

InventoryListing

AWD inventory payload.

Name	Description	Schema
inventory required	List of inventory summaries.	< InventorySummary > array
nextToken optional	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. Example : `"SampleToken"`	string

InventoryQuantity

Quantity of inventory with an associated measurement unit context.

Name	Description	Schema
quantity required	Quantity of the respective inventory.	number
unitOfMeasurement required	Unit of measurement for the inventory.	InventoryUnitOfMeasurement

InventorySummary

Summary of inventory per SKU.

Name	Description	Schema
expirationDetails optional	The expiration details of the inventory. This object will only appear if the `details` parameter in the request is set to `SHOW`.	< ExpirationDetails > array
inventoryDetails optional	Additional inventory details. This object is only displayed if the details parameter in the request is set to `SHOW`.	InventoryDetails
sku required	The seller or merchant SKU.	string
totalInboundQuantity optional	Total quantity that is in-transit from the seller and has not yet been received at an AWD Distribution Center	integer (int64)
totalOnhandQuantity optional	Total quantity that is present in AWD distribution centers.	integer (int64)

InventoryUnitOfMeasurement

Unit of measurement for the inventory.

Type : enum

Value	Description
PRODUCT_UNITS	Measures a discrete amount of product units.
CASES	Measures a discrete amount of cases.
PALLETS	Measures a discrete amount of pallets.

LabelOwner

The entity that labels the products.

Type : enum

Value	Description
AMAZON	Amazon labels the products.
SELF	The seller labels the products.

MeasurementData

Package weight and dimension.

Name	Description	Schema
dimensions optional	Dimensions of the package. Dimensions are required when creating an inbound or outbound order.	PackageDimensions
volume optional	Volume of the package.	PackageVolume
weight required	Weight of the package.	PackageWeight

PackageDimensions

Dimensions of the package.

Name	Description	Schema
height required	Height of the package.	number (double)
length required	Length of the package.	number (double)
unitOfMeasurement required	Unit of measurement for package dimensions.	DimensionUnitOfMeasurement
width required	Width of the package.	number (double)

PackageVolume

Represents the volume of the package with a unit of measurement.

Name	Description	Schema
unitOfMeasurement required	Unit of measurement for the package volume.	VolumeUnitOfMeasurement
volume required	The package volume value.	number (double)

PackageWeight

Represents the weight of the package with a unit of measurement.

Name	Description	Schema
unitOfMeasurement required	Unit of measurement for the package weight.	WeightUnitOfMeasurement
weight required	The package weight value.	number (double)

PrepDetails

The preparation details for a product. This contains the prep category, prep owner, and label owner.
Prep instructions are generated based on the specified category.

Name	Description	Schema
labelOwner optional	The entity that labels the products.	LabelOwner
prepCategory optional	The preparation category for shipping an item to Amazon's fulfillment network.	string
prepInstructions optional	Information that pertains to the preparation of inbound products. This is generated based on the specified category.	< PrepInstruction > array
prepOwner optional	The owner of the preparations, if special preparations are required.	PrepOwner

PrepInstruction

Information pertaining to the preparation of inbound products.

Name	Description	Schema
prepOwner optional	The owner of the preparations, if special preparations are required.	PrepOwner
prepType optional	The type of preparation to be done. For more information about preparing items, refer to Prep guidance on Seller Central.	string

PrepOwner

The owner of the preparations, if special preparations are required.

Type : enum

Value	Description
AMAZON	Amazon owns the preparation.
SELF	The seller owns the preparation

ProductAttribute

Product instance attribute that is not described at the SKU level in the catalog.

Name	Description	Schema
name optional	Product attribute name. Example : `"TestAttribute"`	string
value optional	Product attribute value. Example : `"TestAttributeValue"`	string

ProductQuantity

Represents a product with the SKU details and the corresponding quantity.

Name	Description	Schema
attributes optional	Attributes for this instance of the product. For example, already-prepped, or other attributes that distinguish the product beyond the SKU. Example : `{<br> "name" : "TestAttribute",<br> "value" : "TestAttributeValue"<br>}`	< ProductAttribute > array
quantity required	Product quantity.	integer (int32)
sku required	The seller or merchant SKU.	string
expiration optional	The expiration date for the SKU. Values are in ISO 8601 date-time format.	string (date-time)
prepDetails optional	Preparation details of a product which contains the prep category, prep owner and the label owner. If not passed while creating an inbound order, NO_PREP will be used on the product by-default. Prep instructions will be generated based on the category passed	PrepDetails

ShipmentListing

A list of inbound shipment summaries filtered by the attributes specified in the request.

Name	Description	Schema
nextToken optional	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. Example : `"SampleToken"`	string
shipments optional	List of inbound shipment summaries.	< InboundShipmentSummary > array

SkuQuantity

Quantity details for a SKU as part of a shipment

Name	Description	Schema
expectedQuantity required	Quantity of inventory with an associated measurement unit context.	InventoryQuantity
receivedQuantity optional	Quantity of inventory with an associated measurement unit context.	InventoryQuantity
sku required	The merchant stock keeping unit	string

VolumeUnitOfMeasurement

Unit of measurement for the package volume.

Type : enum

Value	Description
CU_IN	Denotes volume measurement in cubic inches.
CBM	Denotes volume measurement in cubic meters.
CC	Denotes volume measurement in cubic centimeters.

WeightUnitOfMeasurement

Unit of measurement for the package weight.

Type : enum

Value	Description
POUNDS	Denotes weight measurement in pounds.
KILOGRAMS	Denotes weight measurement in kilograms.

SkuQuantities

If equal to SHOW, the response includes the shipment SKU quantity details.

Defaults to HIDE, in which case the response does not contain SKU quantities

Type : enum

Value	Description
SHOW	Show the additional SKU quantity details.
HIDE	Hide the additional SKU quantity details.

Details

Set to SHOW to return summaries with additional inventory details. Defaults to HIDE, which returns only inventory summary totals.

Type : enum

Value	Description
SHOW	Show the additional summarized inventory details.
HIDE	Hide the additional summarized inventory details.

ShipmentStatus

Filter by inbound shipment status.

Type : enum

Value	Description
CREATED	Shipment is created, but hasn't shipped.
SHIPPED	Shipment was picked up by the carrier or was dropped off with the carrier.
IN_TRANSIT	The carrier has notified AWD that the shipment is in transit between the origin and destination nodes.
RECEIVING	The shipment has been partially received.
DELIVERED	The shipment has reached the destination node and has been delivered to the facility yard. The shipment `receive` process at the warehouse will start soon.
CLOSED	No more actions are required for the shipment. This is a final state.
CANCELLED	The shipment is cancelled. This is a final state.

SortBy

Field to sort results by. By default, the response will be sorted by UPDATED_AT.

Type : enum

Value	Description
UPDATED_AT	Sort by the time of update.
CREATED_AT	Sort by the time of creation.

SortOrder

Type : enum

For use with the operation(s): listInboundShipments
Sort the response in ASCENDING or DESCENDING order. By default, the response will be sorted in DESCENDING order.

Value	Description
ASCENDING	Sorts the collection in ascending order.
DESCENDING	Sorts the collection in descending order.

For use with the operation(s): listInventory
Sort the response in ASCENDING or DESCENDING order.

Value	Description
ASCENDING	Sorts the collection in ascending order.
DESCENDING	Sorts the collection in descending order.

Updated 3 days ago