Vendor Shipments API v1 reference

Overview

The Selling Partner API for Retail Procurement Shipments provides programmatic access to retail shipping data for vendors.

Version information

Version : v1

Operations

SubmitShipmentConfirmations

Paths

SubmitShipmentConfirmations

POST /vendor/shipping/v1/shipmentConfirmations

Description

Submits one or more shipment confirmations for vendor orders.

Usage Plans:

Plan type	Rate (requests per second)	Burst
Default	10	10
Selling partner specific	Variable	Variable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

Parameters

Type	Name	Description	Schema
Body	body required	The request schema for the SubmitShipmentConfirmations operation.	SubmitShipmentConfirmationsRequest

Responses

HTTP Code	Description	Schema
202	Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier.	SubmitShipmentConfirmationsResponse

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

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.	SubmitShipmentConfirmationsResponse
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.	SubmitShipmentConfirmationsResponse
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.	SubmitShipmentConfirmationsResponse
413	The request size exceeded the maximum accepted size. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitShipmentConfirmationsResponse
415	The request payload is in an unsupported format. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitShipmentConfirmationsResponse
429	The frequency of requests was greater than allowed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitShipmentConfirmationsResponse
500	An unexpected condition occurred that prevented the server from fulfilling the request. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitShipmentConfirmationsResponse
503	Temporary overloading or maintenance of the server. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. Note: For this status code, the rate limit header is deprecated and no longer returned. x-amzn-RequestId (string):Unique request reference identifier.	SubmitShipmentConfirmationsResponse

Definitions

SubmitShipmentConfirmationsRequest

The request schema for the SubmitShipmentConfirmations operation.

Name	Schema
shipmentConfirmations optional	< ShipmentConfirmation > array

ShipmentConfirmation

Name	Description	Schema
shipmentIdentifier required	Unique shipment ID (not used over the last 365 days).	string
shipmentConfirmationType required	Indicates if this shipment confirmation is the initial confirmation, or intended to replace an already posted shipment confirmation. If replacing an existing shipment confirmation, be sure to provide the identical shipmentIdentifier and sellingParty information as in the previous confirmation.	enum (ShipmentConfirmationType)
shipmentType optional	The type of shipment.	enum (ShipmentType)
shipmentStructure optional	Shipment hierarchical structure.	enum (ShipmentStructure)
transportationDetails optional	Transportation details for this shipment.	TransportationDetails
amazonReferenceNumber optional	The Amazon Reference Number is a unique identifier generated by Amazon for all Collect/WePay shipments when you submit a routing request. This field is mandatory for Collect/WePay shipments.	string
shipmentConfirmationDate required	Date on which the shipment confirmation was submitted.	string (date-time)
shippedDate optional	The date and time of the departure of the shipment from the vendor's location. Vendors are requested to send ASNs within 30 minutes of departure from their warehouse/distribution center or at least 6 hours prior to the appointment time at the Amazon destination warehouse, whichever is sooner. Shipped date mentioned in the shipment confirmation should not be in the future.	string (date-time)
estimatedDeliveryDate optional	The date and time on which the shipment is expected to reach buyer's warehouse. It needs to be an estimate based on the average transit time between ship from location and the destination. The exact appointment time will be provided by the buyer and is potentially not known when creating the shipment confirmation.	string (date-time)
sellingParty required	Name/Address and tax details of the selling party.	PartyIdentification
shipFromParty required	Name/Address and tax details of the ship from party.	PartyIdentification
shipToParty required	Name/Address of the destination warehouse where the shipment is being shipped to.	PartyIdentification
shipmentMeasurements optional	Shipment measurement details.	ShipmentMeasurements
importDetails optional	Provide these fields only if this shipment is a direct import.	ImportDetails
shippedItems required	A list of the items in this shipment and their associated details. If any of the item detail fields are common at a carton or a pallet level, provide them at the corresponding carton or pallet level.	< Item > array
cartons optional	A list of the cartons in this shipment.	< Carton > array
pallets optional	A list of the pallets in this shipment.	< Pallet > array

ShipmentMeasurements

Shipment measurement details.

Name	Description	Schema
grossShipmentWeight optional	Gross weight of the shipment.	Weight
shipmentVolume optional	Volume of the shipment.	Volume
cartonCount optional	Number of cartons present in the shipment. Provide the cartonCount only for unpalletized shipments.	integer
palletCount optional	Number of pallets present in the shipment. Provide the palletCount only for palletized shipments.	integer

TransportationDetails

Name	Description	Schema
carrierScac optional	Code that identifies the carrier for the shipment. The Standard Carrier Alpha Code (SCAC) is a unique two to four letter code used to identify a carrier. Carrier SCAC codes are assigned and maintained by the NMFTA (National Motor Freight Association). This field is mandatory for US, CA, MX shipment confirmations.	string
carrierShipmentReferenceNumber optional	The field also known as PRO number is a unique number assigned by the carrier. It is used to identify and track the shipment that goes out for delivery. This field is mandatory for UA, CA, MX shipment confirmations.	string
transportationMode optional	The mode of transportation for this shipment.	enum (TransportationMode)
billOfLadingNumber optional	Bill Of Lading (BOL) number is the unique number assigned by the vendor. The BOL present in the Shipment Confirmation message ideally matches the paper BOL provided with the shipment, but that is no must. Instead of BOL, an alternative reference number (like Delivery Note Number) for the shipment can also be sent in this field.	string

ImportDetails

Name	Description	Schema
methodOfPayment optional	This is used for import purchase orders only. If the recipient requests, this field will contain the shipment method of payment.	enum (MethodOfPayment)
sealNumber optional	The container's seal number.	string
route optional	The route and stop details for this shipment.	Route
importContainers optional	Types and numbers of container(s) for import purchase orders. Can be a comma-separated list if shipment has multiple containers. maxLength : 64	string
billableWeight optional	Billable weight of the direct imports shipment.	Weight
estimatedShipByDate optional	Date on which the shipment is expected to be shipped. This value should not be in the past and not more than 60 days out in the future.	string (date-time)

Item

Details of the item being shipped.

Name	Description	Schema
itemSequenceNumber required	Item sequence number for the item. The first item will be 001, the second 002, and so on. This number is used as a reference to refer to this item from the carton or pallet level.	string
amazonProductIdentifier optional	Amazon Standard Identification Number (ASIN) of an item.	string
vendorProductIdentifier optional	The vendor selected product identification of the item. Should be the same as was sent in the purchase order.	string
shippedQuantity required	Total item quantity shipped in this shipment.	ItemQuantity
itemDetails optional	Item details for be provided for every item in shipment at either the item or carton or pallet level, whichever is appropriate.	ItemDetails

Carton

Details of the carton/package being shipped.

Name	Description	Schema
cartonIdentifiers optional	A list of carton identifiers.	< ContainerIdentification > array
cartonSequenceNumber required	Carton sequence number for the carton. The first carton will be 001, the second 002, and so on. This number is used as a reference to refer to this carton from the pallet level.	string
dimensions optional	Physical dimensional measurements of a container.	Dimensions
weight optional	The weight.	Weight
trackingNumber optional	This is required to be provided for every carton in the small parcel shipments.	string
items required	A list of container item details.	< ContainerItem > array

Pallet

Details of the Pallet/Tare being shipped.

Name	Description	Schema
palletIdentifiers required	A list of pallet identifiers.	< ContainerIdentification > array
tier optional	Number of layers per pallet.	integer
block optional	Number of cartons per layer on the pallet.	integer
dimensions optional	Physical dimensional measurements of a container.	Dimensions
weight optional	The weight.	Weight
cartonReferenceDetails optional	Carton reference details.	CartonReferenceDetails
items optional	A list of container item details.	< ContainerItem > array

ItemDetails

Item details for be provided for every item in shipment at either the item or carton or pallet level, whichever is appropriate.

Name	Description	Schema
purchaseOrderNumber optional	The Amazon purchase order number for the shipment being confirmed. If the items in this shipment belong to multiple purchase order numbers that are in particular carton or pallet within the shipment, then provide the purchaseOrderNumber at the appropriate carton or pallet level. Formatting Notes: 8-character alpha-numeric code.	string
lotNumber optional	The batch or lot number associates an item with information the manufacturer considers relevant for traceability of the trade item to which the Element String is applied. The data may refer to the trade item itself or to items contained. This field is mandatory for all perishable items.	string
expiry optional	Either expiryDate or mfgDate and expiryAfterDuration are mandatory for perishable items.	Expiry
maximumRetailPrice optional	Maximum retail price of the item being shipped.	Money
handlingCode optional	Identification of the instructions on how specified item/carton/pallet should be handled.	enum (HandlingCode)

ContainerIdentification

Name	Description	Schema
containerIdentificationType required	The container identification type.	enum (ContainerIdentificationType)
containerIdentificationNumber required	Container identification number that adheres to the definition of the container identification type.	string

ContainerItem

Carton/Pallet level details for the item.

Name	Description	Schema
itemReference required	The reference number for the item. Please provide the itemSequenceNumber from the 'items' segment to refer to that item's details here.	string
shippedQuantity required	Total item quantity shipped in this carton/pallet.	ItemQuantity
itemDetails optional	Item details for be provided for every item in shipment at either the item or carton or pallet level, whichever is appropriate.	ItemDetails

CartonReferenceDetails

Name	Description	Schema
cartonCount optional	Pallet level carton count is mandatory for single item pallet and optional for mixed item pallet.	integer
cartonReferenceNumbers required	Array of reference numbers for the carton that are part of this pallet/shipment. Please provide the cartonSequenceNumber from the 'cartons' segment to refer to that carton's details here.	< string > array

PartyIdentification

Name	Description	Schema
address optional	Identification of the party by address.	Address
partyId required	Assigned identification for the party.	string
taxRegistrationDetails optional	Tax registration details of the entity.	< TaxRegistrationDetails > array

TaxRegistrationDetails

Tax registration details of the entity.

Name	Description	Schema
taxRegistrationType required	Tax registration type for the entity.	enum (TaxRegistrationType)
taxRegistrationNumber required	Tax registration number for the entity. For example, VAT ID.	string

Address

Address of the party.

Name	Description	Schema
name required	The name of the person, business or institution at that address.	string
addressLine1 required	First line of the address.	string
addressLine2 optional	Additional street address information, if required.	string
addressLine3 optional	Additional street address information, if required.	string
city optional	The city where the person, business or institution is located.	string
county optional	The county where person, business or institution is located.	string
district optional	The district where person, business or institution is located.	string
stateOrRegion optional	The state or region where person, business or institution is located.	string
postalCode optional	The postal code of that address. It contains a series of letters or digits or both, sometimes including spaces or punctuation.	string
countryCode required	The two digit country code in ISO 3166-1 alpha-2 format.	string
phone optional	The phone number of the person, business or institution located at that address.	string

Route

This is used only for direct import shipment confirmations.

Name	Schema
stops required	< Stop > array

Stop

Contractual or operational port or point relevant to the movement of the cargo.

Name	Description	Schema
functionCode required	Provide the function code.	enum (FunctionCode)
locationIdentification optional	Location identifier.	Location
arrivalTime optional	Date and time of the arrival of the cargo.	string (date-time)
departureTime optional	Date and time of the departure of the cargo.	string (date-time)

Location

Location identifier.

Name	Description	Schema
type optional	Type of location identification.	string
locationCode optional	Location code.	string
countryCode optional	The two digit country code. In ISO 3166-1 alpha-2 format.	string

Dimensions

Physical dimensional measurements of a container.

Name	Description	Schema
length required	The length of the container.	Decimal
width required	The width of the container.	Decimal
height required	The height of the container.	Decimal
unitOfMeasure required	The unit of measure for dimensions.	enum (UnitOfMeasure)

Volume

The volume of the container.

Name	Description	Schema
unitOfMeasure required	The unit of measurement.	enum (UnitOfMeasure)
value required	The measurement value.	Decimal

Weight

The weight.

Name	Description	Schema
unitOfMeasure required	The unit of measurement.	enum (UnitOfMeasure)
value required	The measurement value.	Decimal

Money

An amount of money, including units in the form of currency.

Name	Description	Schema
currencyCode required	Three digit currency code in ISO 4217 format.	string
amount required	A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation. Pattern : ^-?(0\|([1-9]\d*))(\.\d+)?([eE][+-]?\d+)?$.	Decimal

Decimal

A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation.
Pattern : ^-?(0|([1-9]\d*))(\.\d+)?([eE][+-]?\d+)?$.

Type : string

ItemQuantity

Details of item quantity.

Name	Description	Schema
amount required	Amount of units shipped for a specific item at a shipment level. If the item is present only in certain cartons or pallets within the shipment, please provide this at the appropriate carton or pallet level.	integer
unitOfMeasure required	Unit of measure for the shipped quantity.	enum (UnitOfMeasure)
unitSize optional	The case size, in the event that we ordered using cases. Otherwise, 1.	integer

Expiry

Name	Description	Schema
manufacturerDate optional	Production, packaging or assembly date determined by the manufacturer. Its meaning is determined based on the trade item context.	string (date-time)
expiryDate optional	The date that determines the limit of consumption or use of a product. Its meaning is determined based on the trade item context.	string (date-time)
expiryAfterDuration optional	Duration after manufacturing date during which the product is valid for consumption.	Duration

Duration

Name	Description	Schema
durationUnit required	Unit for duration.	enum (DurationUnit)
durationValue required	Value for the duration in terms of the durationUnit.	integer

SubmitShipmentConfirmationsResponse

The response schema for the SubmitShipmentConfirmations operation.

Name	Description	Schema
payload optional	The response payload for the SubmitShipmentConfirmations operation.	TransactionReference
errors optional	A list of error responses returned when a request is unsuccessful.	ErrorList

TransactionReference

Name	Description	Schema
transactionId optional	GUID assigned by Amazon to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction.	string

ErrorList

A list of error responses returned when a request is unsuccessful.

Type : < Error > array

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
message required	A message that describes the error condition.	string
details optional	Additional details that can help the caller understand or fix the issue.	string

MethodOfPayment

This is used for import purchase orders only. If the recipient requests, this field will contain the shipment method of payment.

Type : enum

Value	Description
PaidByBuyer	Buyer pays for shipping.
CollectOnDelivery	Buyer pays for shipping on delivery.
DefinedByBuyerAndSeller	Shipping costs paid as agreed upon between buyer and seller.
FOBPortOfCall	Seller pays for transportation incl. loading, shipping.
PrepaidBySeller	Seller prepays for shipping.
PaidBySeller	Seller pays for shipping.

ShipmentType

The type of shipment.

Type : enum

Value	Description
TruckLoad	Truckload shipping is the movement of large amounts of homogeneous cargo, generally the amount necessary to fill an entire semi-trailer or intermodal container.
LessThanTruckLoad	Shipping does not fill the entire truck.
SmallParcel	Small parcel shipments are under 70 pounds per and shipped in your own packaging or carrier supplied boxes.

TransportationMode

The mode of transportation for this shipment.

Type : enum

Value	Description
Road	The mode of transportation is by Road (on a truck).
Air	The mode of transportation is by Air (on a plane).
Ocean	The mode of transportation is by Ocean (on a ship).

HandlingCode

Identification of the instructions on how specified item/carton/pallet should be handled.

Type : enum

Value	Description
Oversized	A package weighing 150 pounds or less and measuring greater than 130 inches in length and girth is classified as an oversized package.
Fragile	A package containing easily breakable items.
Food	A package containing edible items.
HandleWithCare	A package containing fragile or dangerous items.

TaxRegistrationType

Tax registration type for the entity.

Type : enum

Value	Description
VAT	Value-added tax.
GST	Goods and Services tax.

DurationUnit

Unit for duration.

Type : enum

Value	Description
Days	Days
Months	Months

FunctionCode

Provide the function code.

Type : enum

Value	Description
PortOfDischarge	Port of Discharge is a place where a vessel discharges or unloads some or all of its shipments.
FreightPayableAt	Place where the payment for the freight is made.
PortOfLoading	The port where goods are put on a ship.

ContainerIdentificationType

The container identification type.

Type : enum

Value	Description
SSCC	2 Digit Application Identifier (00) followed by unique 18-digit Serial Shipment Container Code (SSCC) to be included to define a pallet/carton and to identify its contents.
AMZNCC	Amazon Container Code - a substitute for a SSCC that is generated by Amazon for small vendors and associated with a pallet/carton label.
GTIN	Global Trade Identification Number (part of the standard GS1 barcoding and product identification system).
BPS	Barcode Packing Slip.
CID	Container identifier for import shipments.

ShipmentConfirmationType

Indicates if this shipment confirmation is the initial confirmation, or intended to replace an already posted shipment confirmation. If replacing an existing shipment confirmation, be sure to provide the identical shipmentIdentifier and sellingParty information as in the previous confirmation.

Type : enum

Value	Description
Original	Initial shipment confirmation message.
Replace	Replace the original shipment confirmation message.

ShipmentStructure

Shipment hierarchical structure.

Type : enum

Value	Description
PalletizedAssortmentCase	Shipment -> Order -> Pallet/Tare -> Carton/Package -> Item
LooseAssortmentCase	Shipment -> Order -> Carton/Package -> Item
PalletOfItems	Shipment -> Order -> Pallet/Tare -> Item
PalletizedStandardCase	Shipment -> Order -> Pallet/Tare -> Item -> Carton/Package
LooseStandardCase	Shipment -> Order -> Item -> Carton/Package
MasterPallet	Shipment -> Pallet/Tare -> Order -> Item
MasterCase	Shipment -> Carton/Package -> Order -> Item

UnitOfMeasure

Type : enum

For use with the definition(s): Weight The unit of measurement.

Value	Description
G	Grams
Kg	Kilograms
Oz	Ounces
Lb	Pounds

For use with the definition(s): Dimensions The unit of measure for dimensions.

Value	Description
In	Inches
Ft	Feet
Meter	Meters
Yard	Yards

For use with the definition(s): Volume The unit of measurement.

Value	Description
CuFt	Cubic feet.
CuIn	Cubic inches.
CuM	Cubic meter.
CuY	Cubic yard.

For use with the definition(s): ItemQuantity Unit of measure for the shipped quantity.

Value	Description
Cases	Packing of individual items into a case.
Eaches	Individual items.