Shipping API v2 reference

Provides programmatic access to Amazon Shipping v2 APIs.

Overview

The Amazon Shipping API is designed to support outbound shipping use cases both for orders originating on Amazon-owned marketplaces as well as external channels/marketplaces. With these APIs, you can request shipping rates, create shipments, cancel shipments, and track shipments.

Version information

Version : v2

Contact information

Contact : Amazon Shipping API Support
Contact Email : [email protected]

License information

License : Amazon Software License
License URL : https://aws.amazon.com/asl/

URI scheme

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

Consumes

  • application/json

Produces

  • application/json

Operations

getRates
directPurchaseShipment
purchaseShipment
getTracking
getShipmentDocuments
cancelShipment
getAdditionalInputs

Paths

POST /shipping/v2/shipments/rates

Operation: getRates

Description

Returns the available shipping service offerings.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
Bodybody
required
The request schema for the getRates operation. When the channelType is Amazon, the shipTo address is not required and will be ignored.GetRatesRequest
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetRatesResponse
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
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.
ErrorList

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

POST /shipping/v2/shipments/directPurchase

Operation: directPurchaseShipment

Description

Purchases the shipping service for a shipment using the best fit service offering. Returns purchase related details and documents.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
Bodybody
required
The request schema for the directPurchaseShipment operation. When the channel type is Amazon, the shipTo address is not required and will be ignored.DirectPurchaseRequest
Headerx-amzn-IdempotencyKey
optional
A unique value which the server uses to recognize subsequent retries of the same request.string
Headerlocale
optional
The IETF Language Tag. Note that this only supports the primary language subtag with one secondary language subtag (i.e. en-US, fr-CA).
The secondary language subtag is almost always a regional designation.
This does not support additional subtags beyond the primary and secondary language subtags.
string
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
x-amzn-IdempotencyKey (string) : A unique value which the server uses to recognize subsequent retries of the same request.
DirectPurchaseResponse
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
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.
ErrorList

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

POST /shipping/v2/shipments

Operation: purchaseShipment

Description

Purchases a shipping service and returns purchase related details and documents.

Note: You must complete the purchase within 10 minutes of rate creation by the shipping service provider. If you make the request after the 10 minutes have expired, you will receive an error response with the error code equal to "TOKEN_EXPIRED". If you receive this error response, you must get the rates for the shipment again.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
Bodybody
required
The request schema for the purchaseShipment operation.PurchaseShipmentRequest
Headerx-amzn-IdempotencyKey
optional
A unique value which the server uses to recognize subsequent retries of the same request.string
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
PurchaseShipmentResponse
403Indicates 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

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

GET /shipping/v2/tracking

Operation: getTracking

Description

Returns tracking information for a purchased shipment.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
QuerytrackingId
required
A carrier-generated tracking identifier originally returned by the purchaseShipment operation.string
QuerycarrierId
required
A carrier identifier originally returned by the getRates operation for the selected rate.string
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetTrackingResponse
403Indicates 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

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

GET /shipping/v2/shipments/{shipmentId}/documents

Operation: getShipmentDocuments

Description

Returns the shipping documents associated with a package in a shipment.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
PathshipmentId
required
The shipment identifier originally returned by the purchaseShipment operation.string
QuerypackageClientReferenceId
required
The package client reference identifier originally provided in the request body parameter for the getRates operation.string
Queryformat
optional
The file format of the document. Must be one of the supported formats returned by the getRates operation.string
Querydpi
optional
The resolution of the document (for example, 300 means 300 dots per inch). Must be one of the supported resolutions returned in the response to the getRates operation.number
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetShipmentDocumentsResponse
403Indicates 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

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

PUT /shipping/v2/shipments/{shipmentId}/cancel

Operation: cancelShipment

Description

Cancels a purchased shipment. Returns an empty object if the shipment is successfully cancelled.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
PathshipmentId
required
The shipment identifier originally returned by the purchaseShipment operation.string
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
CancelShipmentResponse
403Indicates 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

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

GET /shipping/v2/shipments/additionalInputs/schema

Operation: getAdditionalInputs

Description

Returns the JSON schema to use for providing additional inputs when needed to purchase a shipping offering. Call the getAdditionalInputs operation when the response to a previous call to the getRates operation indicates that additional inputs are required for the rate (shipping offering) that you want to purchase.

Usage Plan:

Rate (requests per second)Burst
80100

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.

Parameters

TypeNameDescriptionSchema
QueryrequestToken
required
The request token returned in the response to the getRates operation.string
QueryrateId
required
The rate identifier for the shipping offering (rate) returned in the response to the getRates operation.string
Headerx-amzn-shipping-business-id
optional
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.enum (X-amzn-shipping-business-id)

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetAdditionalInputsResponse
403Indicates 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

For additional 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 CodeDescriptionSchema
400Request 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
401The request's Authorization header is not formatted correctly or does not contain a valid token.
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.
ErrorList
404The 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
413The 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.
ErrorList
415The 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.
ErrorList
429The 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.
ErrorList
500An 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.
ErrorList
503Temporary 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.
ErrorList

Definitions

Error

Error response returned when the request is unsuccessful.

NameDescriptionSchema
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

ErrorList

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

Type : < Error > array

Weight

The weight in the units indicated.

NameDescriptionSchema
unit
required
The unit of measurement.enum (Unit)
value
required
The measurement value.number

InvoiceDetails

The invoice details for charges associated with the goods in the package. Only applies to certain regions.

NameDescriptionSchema
invoiceNumber
optional
The invoice number of the item.string
invoiceDate
optional
The invoice date of the item in ISO 8061 format.string (date-time)

ChargeList

A list of charges based on the shipping service charges applied on a package.

Type : < ChargeComponent > array

ChargeComponent

The type and amount of a charge applied on a package.

NameDescriptionSchema
amount
optional
The monetary value in the currency indicated, in ISO 4217 standard format.Currency
chargeType
optional
The type of charge.enum (ChargeType)

Currency

The monetary value in the currency indicated, in ISO 4217 standard format.

NameDescriptionSchema
value
required
The monetary value.number
unit
required
The ISO 4217 format 3-character currency code.
minLength : 3
maxLength : 3
string

Dimensions

A set of measurements for a three-dimensional object.

NameDescriptionSchema
length
required
The length of the package.number
width
required
The width of the package.number
height
required
The height of the package.number
unit
required
The unit of measurement.enum (Unit)

RequestToken

A unique token generated to identify a getRates operation.

Type : string

RateId

An identifier for the rate (shipment offering) provided by a shipping service provider.

Type : string

CarrierId

The carrier identifier for the offering, provided by the carrier.

Type : string

CarrierName

The carrier name for the offering.

Type : string

PackageClientReferenceId

A client provided unique identifier for a package being shipped. This value should be saved by the client to pass as a parameter to the getShipmentDocuments operation.

Type : string

ShipmentId

The unique shipment identifier provided by a shipping service.

Type : string

TrackingId

The carrier generated identifier for a package in a purchased shipment.

Type : string

AlternateLegTrackingId

The carrier generated reverse identifier for a returned package in a purchased shipment.

Type : string

ServiceId

An identifier for the shipping service.

Type : string

ServiceName

The name of the shipping service.

Type : string

Address

The address.

NameDescriptionSchema
name
required
The name of the person, business or institution at the address.
minLength : 1
maxLength : 50
string
addressLine1
required
The first line of the address.
minLength : 1
maxLength : 60
string
addressLine2
optional
Additional address information, if required.
minLength : 1
maxLength : 60
string
addressLine3
optional
Additional address information, if required.
minLength : 1
maxLength : 60
string
companyName
optional
The name of the business or institution associated with the address.string
stateOrRegion
required
The state, county or region where the person, business or institution is located.StateOrRegion
city
required
The city or town where the person, business or institution is located.City
countryCode
required
The two digit country code. Follows ISO 3166-1 alpha-2 format.CountryCode
postalCode
required
The postal code of that address. It contains a series of letters or digits or both, sometimes including spaces or punctuation.PostalCode
email
optional
The email address of the contact associated with the address.
maxLength : 64
string
phoneNumber
optional
The phone number of the person, business or institution located at that address, including the country calling code.
minLength : 1
maxLength : 20
string

StateOrRegion

The state, county or region where the person, business or institution is located.

Type : string

City

The city or town where the person, business or institution is located.

Type : string

CountryCode

The two digit country code. Follows ISO 3166-1 alpha-2 format.

Type : string

PostalCode

The postal code of that address. It contains a series of letters or digits or both, sometimes including spaces or punctuation.

Type : string

Location

The location where the person, business or institution is located.

NameDescriptionSchema
stateOrRegion
optional
The state, county or region where the person, business or institution is located.StateOrRegion
city
optional
The city or town where the person, business or institution is located.City
countryCode
optional
The two digit country code. Follows ISO 3166-1 alpha-2 format.CountryCode
postalCode
optional
The postal code of that address. It contains a series of letters or digits or both, sometimes including spaces or punctuation.PostalCode

DocumentFormat

The file format of the document.

Type : enum

ValueDescription
PDFThe Portable Document Format (PDF) file format. Used to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems.
PNGPortable Network Graphics (PNG) is a raster-graphics file format that supports lossless data compression.
ZPLZebra Programming Language (ZPL) format is from Zebra Technologies. It's used primarily for labeling applications and can only be used with ZPL compatible printers.

DocumentType

The type of shipping document.

Type : enum

ValueDescription
PACKSLIPA listing of the items packed within the shipment.
LABELThe shipping label for the specific shipment.
RECEIPTThe receipt of the shipment.
CUSTOM_FORMThe customs documentation for a cross-border shipment.

Dpi

The dots per inch (DPI) value used in printing. This value represents a measure of the resolution of the document.

Type : integer

PageLayout

Indicates the position of the label on the paper. Should be the same value as returned in getRates response.

Type : string

NeedFileJoining

When true, files should be stitched together. Otherwise, files should be returned separately. Defaults to false.

Type : boolean

Contents

A Base64 encoded string of the file contents.

Type : string

PackageDocumentList

A list of documents related to a package.

Type : < PackageDocument > array

PackageDocument

A document related to a package.

NameDescriptionSchema
type
required
The type of shipping document.DocumentType
format
required
The file format of the document.DocumentFormat
contents
required
A Base64 encoded string of the file contents.Contents

PrintOptionList

A list of the format options for a label.

Type : < PrintOption > array

PrintOption

The format options available for a label.

NameDescriptionSchema
supportedDPIs
optional
A list of the supported DPI options for a document.< Dpi > array
supportedPageLayouts
required
A list of the supported page layout options for a document.< PageLayout > array
supportedFileJoiningOptions
required
A list of the supported needFileJoining boolean values for a document.< NeedFileJoining > array
supportedDocumentDetails
required
A list of the supported documented details.< SupportedDocumentDetail > array

DocumentSize

The size dimensions of the label.

NameDescriptionSchema
width
required
The width of the document measured in the units specified.number
length
required
The length of the document measured in the units specified.number
unit
required
The unit of measurement.enum (Unit)

SupportedDocumentDetail

The supported document types for a service offering.

NameDescriptionSchema
name
required
The type of shipping document.DocumentType
isMandatory
required
When true, the supported document type is required.boolean

RequestedDocumentSpecification

The document specifications requested. For calls to the purchaseShipment operation, the shipment purchase fails if the specified document specifications are not among those returned in the response to the getRates operation.

NameDescriptionSchema
format
required
The file format of the document.DocumentFormat
size
required
The size dimensions of the label.DocumentSize
dpi
optional
The dots per inch (DPI) value used in printing. This value represents a measure of the resolution of the document.Dpi
pageLayout
optional
Indicates the position of the label on the paper. Should be the same value as returned in getRates response.PageLayout
needFileJoining
required
When true, files should be stitched together. Otherwise, files should be returned separately. Defaults to false.NeedFileJoining
requestedDocumentTypes
required
A list of the document types requested.< DocumentType > array

SupportedDocumentSpecificationList

A list of the document specifications supported for a shipment service offering.

Type : < SupportedDocumentSpecification > array

SupportedDocumentSpecification

Document specification that is supported for a service offering.

NameDescriptionSchema
format
required
The file format of the document.DocumentFormat
size
required
The size dimensions of the label.DocumentSize
printOptions
required
A list of the format options for a label.PrintOptionList

Item

An item in a package.

NameDescriptionSchema
itemValue
optional
The monetary value in the currency indicated, in ISO 4217 standard format.Currency
description
optional
The product description of the item.string
itemIdentifier
optional
A unique identifier for an item provided by the client.string
quantity
required
The number of units. This value is required.integer
weight
optional
The weight in the units indicated.Weight
isHazmat
optional
When true, the item qualifies as hazardous materials (hazmat). Defaults to false.boolean
productType
optional
The product type of the item.string
invoiceDetails
optional
The invoice details for charges associated with the goods in the package. Only applies to certain regions.InvoiceDetails
serialNumbers
optional
A list of unique serial numbers in an Amazon package that can be used to guarantee non-fraudulent items. The number of serial numbers in the list must be less than or equal to the quantity of items being shipped. Only applicable when channel source is Amazon.< string > array
directFulfillmentItemIdentifiers
optional
Item identifiers for an item in a direct fulfillment shipment.DirectFulfillmentItemIdentifiers

ItemList

A list of items.

Type : < Item > array

Package

A package to be shipped through a shipping service offering.

NameDescriptionSchema
dimensions
required
A set of measurements for a three-dimensional object.Dimensions
weight
required
The weight in the units indicated.Weight
insuredValue
required
The monetary value in the currency indicated, in ISO 4217 standard format.Currency
isHazmat
optional
When true, the package contains hazardous materials. Defaults to false.boolean
sellerDisplayName
optional
The seller name displayed on the label.string
charges
optional
A list of charges based on the shipping service charges applied on a package.ChargeList
packageClientReferenceId
required
A client provided unique identifier for a package being shipped. This value should be saved by the client to pass as a parameter to the getShipmentDocuments operation.PackageClientReferenceId
items
required
A list of items.ItemList

PackageList

A list of packages to be shipped through a shipping service offering.

Type : < Package > array

DirectFulfillmentItemIdentifiers

Item identifiers for an item in a direct fulfillment shipment.

NameDescriptionSchema
lineItemID
required
A unique identifier for an item provided by the client for a direct fulfillment shipment. This is only populated for direct fulfillment multi-piece shipments. It is required if a vendor wants to change the configuration of the packages in which the purchase order is shipped.string
pieceNumber
optional
A unique identifier for an item provided by the client for a direct fulfillment shipment. This is only populated if a single line item has multiple pieces. Defaults to 1.string

PackageDocumentDetail

The post-purchase details of a package that will be shipped using a shipping service.

NameDescriptionSchema
packageClientReferenceId
required
A client provided unique identifier for a package being shipped. This value should be saved by the client to pass as a parameter to the getShipmentDocuments operation.PackageClientReferenceId
packageDocuments
required
A list of documents related to a package.PackageDocumentList
trackingId
optional
The carrier generated identifier for a package in a purchased shipment.TrackingId

PackageDocumentDetailList

A list of post-purchase details about a package that will be shipped using a shipping service.

Type : < PackageDocumentDetail > array

TimeWindow

The start and end time that specifies the time interval of an event.

NameDescriptionSchema
startTime
optional
The start time of the time window.string (date-time)
endTime
optional
The end time of the time window.string (date-time)

Promise

The time windows promised for pickup and delivery events.

NameDescriptionSchema
deliveryWindow
optional
The start and end time that specifies the time interval of an event.TimeWindow
pickupWindow
optional
The start and end time that specifies the time interval of an event.TimeWindow

RequestedValueAddedServiceList

The value-added services to be added to a shipping service purchase.

Type : < RequestedValueAddedService > array

RequestedValueAddedService

A value-added service to be applied to a shipping service purchase.

NameDescriptionSchema
id
required
The identifier of the selected value-added service. Must be among those returned in the response to the getRates operation.string

AvailableValueAddedServiceGroupList

A list of value-added services available for a shipping service offering.

Type : < AvailableValueAddedServiceGroup > array

AvailableValueAddedServiceGroup

The value-added services available for purchase with a shipping service offering.

NameDescriptionSchema
groupId
required
The type of the value-added service group.string
groupDescription
required
The name of the value-added service group.string
isRequired
required
When true, one or more of the value-added services listed must be specified.boolean
valueAddedServices
optional
A list of optional value-added services available for purchase with a shipping service offering.< ValueAddedService > array

ValueAddedService

A value-added service available for purchase with a shipment service offering.

NameDescriptionSchema
id
required
The identifier for the value-added service.string
name
required
The name of the value-added service.string
cost
required
The cost of the value-added service.Currency

CollectOnDelivery

The amount to collect on delivery.

NameDescriptionSchema
amount
required
The monetary value in the currency indicated, in ISO 4217 standard format.Currency

ValueAddedServiceDetails

A collection of supported value-added services.

NameDescriptionSchema
collectOnDelivery
optional
The amount to collect on delivery.CollectOnDelivery

TaxType

Indicates the type of tax.

Type : enum

ValueDescription
GSTGoods and Services Tax.

TaxDetail

Indicates the tax specifications associated with the shipment for customs compliance purposes in certain regions.

NameDescriptionSchema
taxType
required
Indicates the type of tax.TaxType
taxRegistrationNumber
required
The shipper's tax registration number associated with the shipment for customs compliance purposes in certain regions.string

TaxDetailList

A list of tax detail information.

Type : < TaxDetail > array

EventCode

The tracking event type.

Type : enum

ValueDescription
ReadyForReceivePackage has been created and is ready for pickup at the shippers location. This is a pre-transit status event code.
PickupDonePackage has been picked up by the service provider.
DeliveredPackage has been delivered.
DepartedPackage has departed from a particular location in carrier network.
DeliveryAttemptedDelivery was attempted, but was unsuccessful.
LostPackage is lost.
OutForDeliveryPackage is out for delivery.
ArrivedAtCarrierFacilityPackage is in transit and has been received at a carrier location.
RejectedPackage was rejected by the recipient.
UndeliverablePackage is undeliverable.
PickupCancelledPickup scheduled for the package was cancelled.

Event

A tracking event.

NameDescriptionSchema
eventCode
required
The tracking event type.EventCode
location
optional
The location where the person, business or institution is located.Location
eventTime
required
The ISO 8601 formatted timestamp of the event.string (date-time)

TrackingSummary

A package status summary.

NameDescriptionSchema
status
optional
The status of the package being shipped.Status

Status

The status of the package being shipped.

Type : enum

ValueDescription
PreTransitPackage has been created but has not been picked up.
InTransitPackage has been picked up and is in transit.
DeliveredPackage has has been delivered successfully.
LostPackage is lost.
OutForDeliveryPackage is out for delivery.
RejectedPackage has been rejected by the recipient.
UndeliverablePackage was undeliverable.
DeliveryAttemptedDelivery was attempted to the recipient location, but was not delivered.
PickupCancelledPickup was cancelled for the package.

AmazonOrderDetails

Amazon order information. This is required if the shipment source channel is Amazon.

NameDescriptionSchema
orderId
required
The Amazon order ID associated with the Amazon order fulfilled by this shipment.string

AmazonShipmentDetails

Amazon shipment information.

NameDescriptionSchema
shipmentId
required
This attribute is required only for a Direct Fulfillment shipment. This is the encrypted shipment ID.string

ChannelDetails

Shipment source channel related information.

NameDescriptionSchema
channelType
required
The shipment source channel type.enum (ChannelType)
amazonOrderDetails
optional
Amazon order information. This is required if the shipment source channel is Amazon.AmazonOrderDetails
amazonShipmentDetails
optional
Amazon shipment information.AmazonShipmentDetails

RateList

A list of eligible shipping service offerings.

Type : < Rate > array

Rate

The details of a shipping service offering.

NameDescriptionSchema
rateId
required
An identifier for the rate (shipment offering) provided by a shipping service provider.RateId
carrierId
required
The carrier identifier for the offering, provided by the carrier.CarrierId
carrierName
required
The carrier name for the offering.CarrierName
serviceId
required
An identifier for the shipping service.ServiceId
serviceName
required
The name of the shipping service.ServiceName
billedWeight
optional
The weight in the units indicated.Weight
totalCharge
required
The monetary value in the currency indicated, in ISO 4217 standard format.Currency
promise
required
The time windows promised for pickup and delivery events.Promise
supportedDocumentSpecifications
required
A list of the document specifications supported for a shipment service offering.SupportedDocumentSpecificationList
availableValueAddedServiceGroups
optional
A list of value-added services available for a shipping service offering.AvailableValueAddedServiceGroupList
requiresAdditionalInputs
required
When true, indicates that additional inputs are required to purchase this shipment service. You must then call the getAdditionalInputs operation to return the JSON schema to use when providing the additional inputs to the purchaseShipment operation.boolean

IneligibilityReasonCode

Reasons that make a shipment service offering ineligible.

Type : enum

ValueDescription
NO_COVERAGEThe shipment is ineligible because there is no coverage to that address.
PICKUP_SLOT_RESTRICTIONThe shipment is ineligible because there is an issue with the pickup slot.
UNSUPPORTED_VASThe shipment is ineligible because the value-added service is invalid for this shipment.
VAS_COMBINATION_RESTRICTIONThe shipment is ineligible because an invalid combination of value-added services were chosen.
SIZE_RESTRICTIONSThe shipment is ineligible because the package dimensions are unsupported.
WEIGHT_RESTRICTIONSThe shipment is ineligible because the weight is unsupported.
LATE_DELIVERYThe shipment is ineligible because delivery is too late.
PROGRAM_CONSTRAINTSThe shipment is ineligible because of program constraints.
TERMS_AND_CONDITIONS_NOT_ACCEPTEDThe shipment is ineligible because terms and conditions have not been accepted by the carrier.
UNKNOWNThe ineligibility reason is unknown.

IneligibilityReason

The reason why a shipping service offering is ineligible.

NameDescriptionSchema
code
required
Reasons that make a shipment service offering ineligible.IneligibilityReasonCode
message
required
The ineligibility reason.string

IneligibleRate

Detailed information for an ineligible shipping service offering.

NameDescriptionSchema
serviceId
required
An identifier for the shipping service.ServiceId
serviceName
required
The name of the shipping service.ServiceName
carrierName
required
The carrier name for the offering.CarrierName
carrierId
required
The carrier identifier for the offering, provided by the carrier.CarrierId
ineligibilityReasons
required
A list of reasons why a shipping service offering is ineligible.< IneligibilityReason > array

IneligibleRateList

A list of ineligible shipping service offerings.

Type : < IneligibleRate > array

CancelShipmentResult

The payload for the cancelShipment operation.

Type : object

CancelShipmentResponse

Response schema for the cancelShipment operation.

NameDescriptionSchema
payload
optional
The payload for the cancelShipment operation.CancelShipmentResult

GetRatesRequest

The request schema for the getRates operation. When the channelType is Amazon, the shipTo address is not required and will be ignored.

NameDescriptionSchema
shipTo
optional
The ship to address.Address
shipFrom
required
The ship from address.Address
returnTo
optional
The return to address.Address
shipDate
optional
The ship date and time (the requested pickup). This defaults to the current date and time.string (date-time)
packages
required
A list of packages to be shipped through a shipping service offering.PackageList
valueAddedServices
optional
A collection of supported value-added services.ValueAddedServiceDetails
taxDetails
optional
A list of tax detail information.TaxDetailList
channelDetails
required
Shipment source channel related information.ChannelDetails

GetRatesResult

The payload for the getRates operation.

NameDescriptionSchema
requestToken
required
A unique token generated to identify a getRates operation.RequestToken
rates
required
A list of eligible shipping service offerings.RateList
ineligibleRates
optional
A list of ineligible shipping service offerings.IneligibleRateList

GetRatesResponse

The response schema for the getRates operation.

NameDescriptionSchema
payload
optional
The payload for the getRates operation.GetRatesResult

DirectPurchaseRequest

The request schema for the directPurchaseShipment operation. When the channel type is Amazon, the shipTo address is not required and will be ignored.

NameDescriptionSchema
shipTo
optional
The address where the shipment will be delivered. For vendor orders, shipTo information is pulled directly from the Amazon order.Address
shipFrom
optional
The address where the package will be picked up.Address
returnTo
optional
The address where the package will be returned if it cannot be delivered.Address
packages
optional
A list of packages to be shipped through a shipping service offering.PackageList
channelDetails
required
Shipment source channel related information.ChannelDetails
labelSpecifications
optional
The document (label) specifications requested. The default label returned is PNG DPI 203 4x6 if no label specification is provided. Requesting an invalid file format results in a failure.RequestedDocumentSpecification

DirectPurchaseResult

The payload for the directPurchaseShipment operation.

NameDescriptionSchema
shipmentId
required
The unique shipment identifier provided by a shipping service.ShipmentId
packageDocumentDetailList
optional
A list of post-purchase details about a package that will be shipped using a shipping service.PackageDocumentDetailList

DirectPurchaseResponse

The response schema for the directPurchaseShipment operation.

NameDescriptionSchema
payload
optional
The payload for the directPurchaseShipment operation.DirectPurchaseResult

GetShipmentDocumentsResult

The payload for the getShipmentDocuments operation.

NameDescriptionSchema
shipmentId
required
The unique shipment identifier provided by a shipping service.ShipmentId
packageDocumentDetail
required
The post-purchase details of a package that will be shipped using a shipping service.PackageDocumentDetail

GetShipmentDocumentsResponse

The response schema for the the getShipmentDocuments operation.

NameDescriptionSchema
payload
optional
The payload for the getShipmentDocuments operation.GetShipmentDocumentsResult

GetTrackingResult

The payload for the getTracking operation.

NameDescriptionSchema
trackingId
required
The carrier generated identifier for a package in a purchased shipment.TrackingId
alternateLegTrackingId
required
The carrier generated reverse identifier for a returned package in a purchased shipment.AlternateLegTrackingId
eventHistory
required
A list of tracking events.< Event > array
promisedDeliveryDate
required
The date and time by which the shipment is promised to be delivered.string (date-time)
summary
required
A package status summary.TrackingSummary

GetTrackingResponse

The response schema for the getTracking operation.

NameDescriptionSchema
payload
optional
The payload for the getTracking operation.GetTrackingResult

PurchaseShipmentRequest

The request schema for the purchaseShipment operation.

NameDescriptionSchema
requestToken
required
A unique token generated to identify a getRates operation.RequestToken
rateId
required
An identifier for the rate (shipment offering) provided by a shipping service provider.RateId
requestedDocumentSpecification
required
The document specifications requested. For calls to the purchaseShipment operation, the shipment purchase fails if the specified document specifications are not among those returned in the response to the getRates operation.RequestedDocumentSpecification
requestedValueAddedServices
optional
The value-added services to be added to a shipping service purchase.RequestedValueAddedServiceList
additionalInputs
optional
The additional inputs required to purchase a shipping offering, in JSON format. The JSON provided here must adhere to the JSON schema that is returned in the response to the getAdditionalInputs operation.

Additional inputs are only required when indicated by the requiresAdditionalInputs property in the response to the getRates operation.
object

PurchaseShipmentResult

The payload for the purchaseShipment operation.

NameDescriptionSchema
shipmentId
required
The unique shipment identifier provided by a shipping service.ShipmentId
packageDocumentDetails
required
A list of post-purchase details about a package that will be shipped using a shipping service.PackageDocumentDetailList
promise
required
The time windows promised for pickup and delivery events.Promise

PurchaseShipmentResponse

The response schema for the purchaseShipment operation.

NameDescriptionSchema
payload
optional
The payload for the purchaseShipment operation.PurchaseShipmentResult

GetAdditionalInputsResult

The JSON schema to use to provide additional inputs when required to purchase a shipping offering.

Type : object

GetAdditionalInputsResponse

The response schema for the getAdditionalInputs operation.

NameDescriptionSchema
payload
optional
The JSON schema to use to provide additional inputs when required to purchase a shipping offering.GetAdditionalInputsResult

ChargeType

The type of charge.

Type : enum

ValueDescription
TAXA tax imposed on a package.
DISCOUNTA discount deducted from the cost of a package.

X-amzn-shipping-business-id

Amazon shipping business to assume for this request. The default is AmazonShipping_UK.

Type : enum

ValueDescription
AmazonShipping_USThe United States Amazon shipping business.
AmazonShipping_INThe India Amazon shipping business.
AmazonShipping_UKThe United Kingdom Amazon shipping business.
AmazonShipping_UAEThe United Arab Emirates Amazon shipping business.
AmazonShipping_SAThe Saudi Arabia Amazon shipping business.
AmazonShipping_EGThe Egypt Amazon shipping business.
AmazonShipping_ITThe Italy Amazon shipping business.

ChannelType

The shipment source channel type.

Type : enum

ValueDescription
AMAZONIndicates that the shipment originates from an Amazon order.
EXTERNALIndicates that the shipment originates from a non-Amazon channel.

Unit

Type : enum

For use with the definition(s): Dimensions, DocumentSize
The unit of measurement.

ValueDescription
INCHThe imperial unit of length equal to one twelfth of a foot.
CENTIMETERA metric unit of length, equal to one hundredth of a meter.

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

ValueDescription
GRAMMetric unit of mass equal to one thousandth of a kilogram.
KILOGRAMMetric unit of mass.
OUNCEThe imperial unit of weight that is one sixteenth of a pound.
POUNDThe imperial unit of weight.

Did this page help you?