Shipping API Use Case Guide

Version: 3.2
Date: 7/4/2020
Table of Contents
What is the Shipping API? ....................................................................................................... 4
Tutorial: Purchase a shipment from a rate .............................................................................. 7
Step 1. Get rates for a shipment ....................................................................................................... 7
Step 2. Discover required additional inputs for a shipment ............................................................ 12
Step 3. Purchase a shipment .......................................................................................................... 14
Tutorial: Purchase a shipment directly .................................................................................. 16
Step 1. Purchase a shipment directly .............................................................................................. 16
Tutorial: Retrieve previously generated shipment documents ............................................... 20
Step 1. Retrieve previously generated shipping documents ............................................................ 20
Tutorial: Track a shipment .................................................................................................... 21
Step 1. Track a shipment ................................................................................................................ 22
Tutorial: Cancel a shipment .................................................................................................. 23
Step 1. Cancel a shipment .............................................................................................................. 23
Shipping data types ............................................................................................................... 24
Address .......................................................................................................................................... 25
Package.......................................................................................................................................... 26
Dimension ...................................................................................................................................... 26
Weight ........................................................................................................................................... 27
Currency ........................................................................................................................................ 27
Item ............................................................................................................................................... 27
Direct Fulfillment Item Identifiers .................................................................................................. 28
Channel Details .............................................................................................................................. 28
Amazon Order Details .................................................................................................................... 28
Rate ............................................................................................................................................... 29
Supported Document Specification ................................................................................................ 30
Document Size ............................................................................................................................... 30
Print Options .................................................................................................................................. 30
Requested Document Specification ................................................................................................ 31
Supported Document Detail ........................................................................................................... 32
Available Value Added Service Groups ........................................................................................... 33
Value Added Service ...................................................................................................................... 33
Ineligible Rates............................................................................................................................... 33
Ineligible Reason ............................................................................................................................ 34
Requested Value Added Service ..................................................................................................... 34
Package Document Details ............................................................................................................. 34
Package Document......................................................................................................................... 35
Promise .......................................................................................................................................... 35
Time Window ................................................................................................................................. 35
Event.............................................................................................................................................. 35
Location ......................................................................................................................................... 36
Shipping API User Guide
What is the Shipping API?
Amazon’s Shipping APIs are 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.

Workflow for creating a shipment

Creating a shipment is a multi-step process that includes calls to the Shipping APIs. Here’s the recommended
workflow for creating a shipment.

1) Call the getRates operation to get a set of eligible rate for the shipment.

2) Amazon returns a set of eligible rates for the shipment.

3) (Conditional) Call the additionalInputs operations if directed to do so from the getRates operation to
discover additional data required to purchase a shipment.

4) Call the purchaseShipment operation with the required additional inputs to create a shipment.

5) Amazon will create a shipment from the provided inputs.

Alternatively, Amazon can purchase the best fit ship option for the package by utilizing our direct purchase
operation. This only available for the Direct Fulfillment programs and Non-Amazon orders at the moment.

1) Call the directPurchase operation to create a shipment.

Once a shipment is created, the Shipping APIs provides operations to manage a shipment. (Note: These
operations are not available for the Direct Fulfillment program.)

• Call the getTracking operation to get the current status and tracking history of a given trackingID.

• Call the getShippingDocuments operation to documents associated with the shipment.

• Call the cancelShipment operation to cancel the packages associated with the shipment.
Here is the recommended workflow for creating an Amazon Marketplace or Non-Amazon order shipment:

Here is the recommended workflow for creating a Direct Fulfillment or Non-Amazon shipment where rates do not
need to be known:
Here is the recommended workflow for managing a shipment. These operations are not available for Direct
Fulfillment shipments.

Terminology
• Shipment. A set of packages that are being sent together with the same service offering, from the same
origin address, and to the same destination address. With the exception of printing labels and tracking
packages, all Shipping API calls work at the shipment level.
• Package. An individual parcel in a shipment. Amazon Shipping assigns tracking numbers at the package
level, so you will print a label and get tracking information for each individual package in a shipment.
• Service Name. A shipping service available for purchase. For Amazon Marketplace orders, a list of eligible
service name and carriers is returned in the response. For other channel orders, only eligible Amazon
Shipping service name are returned in the getRates operation response.
• Rate. A collection of shipping service name, pickup window, promised delivery date, base price and
eligible value added services available for a given shipping service.
• Value Added Service. A service added to a base shipping rate. This can include services such as insurance,
or signature on delivery. The getRates operation will return all available VAS’s represented as individual
VAS ID’s for a given shipping service, which you can then request when calling the purchaseShipment API
in the {requestedValueAddedServices} request object.
• Document Types. A variety of documentation produced to facilitate the shipment. The available
document types are Label, Packslip (Only Amazon orders), Receipt (Only Amazon orders), Customs Form
(Only Amazon orders).
 Endpoint Verb URL Purpose
Get Rates POST /shipping/v2/shipments/rates Exploratory call that retrieves the list of
rates for a given shipment, list of rejected
shipping services and optional value-
added services that user can purchase for
given input.
Purchase POST /shipping/v2/shipments Purchases and returns a label based on
Shipment given rateID.

Direct POST /shipping/v2/shipments/directPurchase Purchases and returns a label based on

Purchase best service fit.
Shipment
Get GET /shipping/v2/shipments/additionalInputs When additional inputs are required for a
Additional /schema given shipping service (as notified in the
Inputs Get Rates response) this API returns the
additional required field schema required
to purchase the specified RateID.
Get GET /shipping/v2/shipments/{shipmentID}/do Retrieve a shipping label or other shipping
Shipping cuments documents for a previously created
Documents shipment.
Get GET /shipping/v2/tracking Get the tracking status for an Amazon
Tracking Shipping package.
Cancel PUT /shipping/v2/shipments/{shipmentId}/ca Cancel a previously created label that has
Shipment ncel not been picked up.

Tutorial: Purchase a shipment from a rate

This tutorial shows how to purchase a shipment from a rate. Purchasing a shipment from a rate
comprises of three subtasks: getting rates for a specific shipment, understanding if additional inputs are
required, and the purchasing a shipment.
Prerequisites
To complete these tutorials you will need:
- Enrollment in an eligible program. The eligible programs and subsequent prerequisites are:
o Enrollment in Amazon Shipping with an account that is enabled to ship Amazon or non-
Amazon orders with Amazon Shipping.
- A Seller account if you are an Amazon seller or are working with an Amazon seller to create and
manage shipments.
- Authorization from the shipper for whom you are making calls. See Selling Partner API
Developer Guide for more information.

Step 1. Get rates for a shipment

Step 2. Get additional required inputs for the shipment
Step 3. Purchasing the specific shipment

Step 1. Get rates for a shipment

Getting a rate returns eligible shipping services for a given address, package specifications and/or pickup
slot and provides a delivery promise consisting of: pickup time range and receive (delivery) window. If
pickup slot was not specified by the user input, then the value for next eligible slot will be returned.
If you are fulfilling an Amazon Order, the Amazon Order number must be specifically noted in the
Channel Details.

Amazon Order Non-Amazon Order

NOTE: At this time, each shipment is limited to a single package. However, in the future this limitation
will be removed and shipments may include multiple packages. The API is designed to anticipate this
change. Packages are always input, stored, and output in list form. You should write your API integration
to work with lists of packages. This will keep your integration forward-compatible with multi-package
shipments.

Task
Task 1. Call the getRates operation

Task 1. Call the getRates operation

Call the GetRates operation of Shipping API to get a rate for a shipment.
1. Call the getRates operation of the Shipping API, passing the following request body:

Request Body:
Name Description Required
shipTo The address object where the shipment will be delivered to. Only Conditional
required for Off-Amazon orders. For Amazon orders, shipTo
information is pulled directly from the Amazon order.
Type: Address
shipFrom The address object where the package will be picked up from. Yes
Type: Address
returnTo The address object where the package will be returned to if No
undeliverable.
Type: Address
shipDate The ship date and time (the requested pickup day). This defaults No
to the current date and time if left blank.
Type: String (date-time)
packages Object to list each package and package details. Yes
Type: List of Packages
channelDetails Object to contain order information. Yes
Type: Channel Detail

Request example:
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
HTTP/1.1

Authorization: Bearer <token>

{
"shipTo": {
"name": "Alice",
"addressLine1": "444, St 20, Pete Avenue",
"stateOrRegion": "Texas",
"city": "North Park",
"countryCode": "US",
"postalCode": "78799"
},
"shipFrom": {
"name": "Bob",
"addressLine1": "123, Block 7, Winfield Apartments",
"addressLine2": "North Lamar",
"stateOrRegion": "Texas",
"city": "Demtin",
"countryCode": "US",
"postalCode": "78732"
},
"shipDate": "2020-01-30T09:27:05Z",
"packages": [
{
"dimensions": {
"length": 10,
"width": 8,
"height": 7,
"unit": "INCH"
},
"weight": {
"unit": "GRAM",
"value": 250
},
"insuredValue": {
"value": 44,
"unit": "USD"
},
"isHazmat": true,
"packageClientReferenceId": "PPEI-4326495734098",
"items": [
{
"itemValue": {
"value": 24,
"unit": "USD"
},
"description": "A very shippable item.",
 "itemIdentifier": "ITEM-26495734098",
"quantity": 1,
"weight": {
"unit": "GRAM",
"value": 150
},
"isHazmat": true
},
{
"itemValue": {
"value": 20,
"unit": "USD"
},
"description": "Another great shippable item",
"itemIdentifier": "ITEM-26495734099",
"quantity": 1,
"weight": {
"unit": "GRAM",
"value": 100
},
"isHazmat": false
}
]
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}

Response
A successful response includes the following elements:
Rates Response
Name Description Required
requestToken Unique token generated by Amazon for a rate request.
Yes
Type: String
rates List of eligible shipping service offerings Yes
Type: list of Rates
ineligibleRates List of services that were for some reason unavailable No
for this request. Only returned if there are ineligible
rates.
Type: list of Ineligible Rates

Response example:
HTTP/1.1 200 OK

"payload": {
"requestToken": "6DCCEDD3FF961C15FEB94F342D41C",
"rates": [
{
"rateId": "F4B68849F969E239FF9FCA9C12E35",
"carrierId": "FOOSHIPGRD",
"carrierName": "FOO SHIP GRD",
"billedWeight": {
"value": 5,
"unit": "GRAM"
},
"totalCharge": {
"value": 7,
"unit": "USD"
},
"serviceId": "econ-uk-mfn",
"serviceName": "Amazon Standard",
"promise": {
"deliveryWindow": {
"startTime": "2018-08-24T08:22:30.737Z",
"endTime": "2018-08-24T20:22:30.737Z"
},
"pickupWindow": {
"startTime": "2018-08-23T08:22:30.737Z",
"endTime": "2018-08-23T20:22:30.737Z"
}
},
"supportedDocumentSpecifications": [
{
"format": "PNG",
"size": {
"length": 6,
"width": 4,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"LEFT",
"RIGHT"
],
"supportedFileJoiningOptions": [
true,
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
}
],
 "availableValueAddedServiceGroups": [
{
"groupId": "SIG_VERIFICATION",
"groupDescription": "Signature Verification",
"isRequired": true,
"valueAddedServices": [
{
"id": "CUST_SIG_VERIFICATION",
"name": "Customer Signature Verification",
"cost": {
"unit": "USD",
"value": 2
}
}
]
}
],
"requiresAdditionalInputs" : false
}
],
"ineligibleRates": [
{
"carrierId": "FOOSTDGRD",
"serviceId": "FOO8420430",
"carrierName": "FOOSTDGRD",
"serviceName": "FOO8420430",
"ineligibilityReasons": [
{
"code" : "NO_COVERAGE",
"message" : "Required shipping network coverage doesn't exist for
the offering"
}
]
}
]
}
}

Step 2. Discover required additional inputs for a shipment

After you call the getRates operation, you will need to call the getAdditionalInputs operation only if the
GetRates response for a shipping service returns the [requiresAdditionalInput] field as [true] with the
corresponding [rateID] to identify the additional required fields for that given shipping service to
discover required additional inputs. The getAdditionalInputs operation is used to understand what
additional inputs are required (if any) to create a shipment following a rate call. The below response
fields represent the schema (not actual fields) which will be returned that allow you to build dynamic
forms for your end user to fill in any additional information required for a given shipment.

NOTE: These fields may change as customs/regulatory rules change in different geographies, so it is
recommended to not cache/hardcode these fields for future shipment purchase calls.

Tasks
Task 1. Call the getAdditionalInputs operation
Task 1. Call the getAdditionalInputs operation
Call the getAdditionalInputs operation of Shipping API to get a rate for a shipment.
1. Call the getAdditionalInputs operation of the Shipping API, passing the following query
parameters:

Query parameters:
Name Description Required
requestToken Unique token provided in the Get Rates Yes
response. Used to maintain Idempotency.
Type: String
rateId Identifier for a rate offering returned by the Yes
Rates API.
Type: String

Request example:
POST https://sellingpartnerapi-
eu.amazon.com/shipping/v2/shipments/additionalInputs/schema?requestToken=
amzn1.rq.123456789.101&rateId= 122324234543535321345436534321423423523452345

HTTP/1.1

Authorization: Bearer <token>

Response
A successful response includes the following elements:
Name Description Required
payload JSON Schema for additional inputs required to
purchase. Yes
Type: String

Response example:

HTTP/1.1 200 OK
{
"payload": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Additional inputs for Shipping Offering",
"type": "object",
"properties": {
"harmonizedSystemCode": {
"type": "String",
"description": "Harmonized System's commodity code for an item"
},
"packageClientReferenceId": {
"type": "String",
"description": "Unqiue identifier for the item"
}
}
}

Step 3. Purchase a shipment

After getting rates and discovering additional inputs if required, the shipment can now we purchased. If
additional inputs are required for a given rateID, this operation accepts these additional inputs as
request payload.
NOTE: At this time each shipment is limited to a single package. If you are fulfilling an order with
multiple packages, please create a separate shipment for each package. In the future this limitation will
be removed and you will be able to send a multi-package order using a single, multi-container shipment.

Task
Task 1. Call the purchaseShipment operation

Task 1. Call the purchaseShipment operation

Call the purchaseShipment operation of the Shipping API to create a shipment.
1. Call purchaseShipment operation using the following request body.

Request Body:
Name Description Required
requestToken Unique token provided in the Get Rates Yes
response. Used to maintain Idempotency.
Type: String
rateId rateID selected from the list of rates given as Yes
part of getRates Response.
Type: String
requestedDocumentSpecification Object to define desired label specification. Yes
*Note: Supported label formats are found in
each rate response.
Type: Requested Document Specification
requestedValueAddedServices List of VAS ID’s requested to purchase. No
Type: Requested Value Added Service
additionalInputs Additional inputs required to purchase an No
offering. JSON should adhere to the json
schema returned in
GetAdditionalInputsResponse. Applicable only
if 'requiresAdditionalInputs' field of GetRates
response is true.
Type: String

Request example:
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments
HTTP/1.1

Authorization: Bearer <token>

{
"requestToken": "6DCCEDD3FF961C15FEB94F342D41C",
"rateId": "F4B68849F969E239FF9FCA9C12E35",
"requestedDocumentSpecification": {
"format": "PDF",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"dpi": 203,
"pageLayout": "LEFT",
"needFileJoining": false,
"requestedDocumentTypes": [
"LABEL"
]
},
"requestedValueAddedServices": [
{
"id": "CUST_SIG"
}
],
"additionalInputs": {
"harmonizedSystemCode": "HS1234534",
"packageClientReferenceId": "PAC1234"
}

Response
A successful response includes the following elements:
Name Description Required
shipmentID A unique identifier for a shipment that will be
generated by Amazon. Yes
Type: String
packageDocumentDetails Post-Purchase details of each package. This is a list Yes
of packages created within a single shipment.
Type: Package Document Details
promise Promised pickup and delivery time windows for a Yes
given shipment.
Type: Promise

Response example:
HTTP/1.1 200 OK

"payload": {
"shipmentId": "'878522117881'",
"packageDocumentDetails": [
{
"packageClientReferenceId": "abcd",
"packageDocuments": [
{
"type": "LABEL",
"format": "PNG",
 "contents": "sdioadaiosfhdodsaiufhouafhoudfhdouahfac=="
}
],
"trackingId": "'157864826197'"
}
],
"promise": {
"pickupWindow": {
"startTime": "2019-12-11T07:09:05.513Z",
"endTime": "2019-12-11T09:09:05.513Z"
},
"deliveryWindow": {
"startTime": "2019-12-13T07:09:05.513Z",
"endTime": "2019-12-13T09:09:05.513Z"
}
}
}

Tutorial: Purchase a shipment directly

This tutorial shows how to purchase a shipment directly. You will want to use this endpoint if you are
shipping a Direct Fulfillment order or a Non-Amazon order where you do not need to inquire for rates.
Amazon will select the best fit ship option for Direct Fulfilment shipments and Non-Amazon shipments
when using this operation. Purchasing a shipment directly takes a single step.
Prerequisites
To complete this tutorial you will need:
- Enrollment in an eligible program that supports direct purchase shipment. The eligible programs
and subsequent prerequisites are:
o Enrollment in the Direct Fulfillment program where you will need a Vendor Central
account if you are an Amazon vendor.
o Enrollment in Amazon Shipping with an account that is enabled to ship non-Amazon
orders with Amazon Shipping.
- Authorization from the Vendor or shipper to create and manage shipments for whom you are
making calls. See Selling Partner API Developer Guide for more information.

Step 1. Purchase a shipment directly

Step 1. Purchase a shipment directly

Purchasing a shipment directly will purchase the best fit ship option. If you are fulfilling a Direct
Fulfillment order, please include the DirectFulfillmentItemIdentifiers in the Items object.

Task
Task 1. Call the directPurchase operation

Task 1. Call the directPurchase operation

Call the DirectPurchase operation of Shipping API to get purchase a label directly without a rates
request.
2. Call the directPurchase operation of the Shipping API, passing the following request body:
Request Body:
Name Description Required
shipTo The address object where the shipment will be delivered to. Conditional
Only required for Non-Amazon orders. For Vendor orders,
shipTo information is pulled directly from the Amazon order.
We recommend sending this attribute to simplify your logic.
Type: Address
shipFrom The address object where the package will be picked up from. Conditional
Only required for Non-Amazon orders. For Vendor orders,
shipTo information is pulled directly from the order. We
recommend sending this attribute to simplify your logic.
Type: Address
returnTo The address object where the package will be returned to if No
undeliverable.
Type: Address
shipDate The ship date and time (the requested pickup time). This No
defaults to the current date and time if left blank. Only Non-
Amazon orders can take advantage of requested pickup times.
Type: String (date-time)
packages Object to list each package and package details. This is optional Conditional
for Direct Fulfillment orders if the order is from an Amazon
label vendor.
Type: List of Packages
channelDetails Object to contain order origin information (i.e. Amazon or Yes
External).
Type: Channel Detail
labelSpecifications Object to define desired label specification. The default label No
returned will be PNG DPI 203 4x6 if no label specification is
provided. Requesting an invalid format type will result in a
failure, however, the API will return a label of DPI 300 if an
invalid DPI is passed in the request.
Type: Requested Document Specification

Request example:
POST https://sellingpartnerapi-
eu.amazon.com/shipping/v2/shipments/directPurchase

HTTP/1.1

Authorization: Bearer <token>

{
"shipTo": {
"name": "Alice",
"addressLine1": "444 Pete Avenue",
"stateOrRegion": "Texas",
"city": "Austin",
"countryCode": "US",
 "postalCode": "78799"
},
"shipFrom": {
"name": "Bob",
"addressLine1": "1601 S Lane St ",
"addressLine2": "Apt 521",
"stateOrRegion": "WA",
"city": "Seattle",
"countryCode": "US",
"postalCode": "98144"
},
"shipDate": "2020-01-30T09:27:05Z",
"packages": [
{
"dimensions": {
"length": 10,
"width": 8,
"height": 5,
"unit": "INCH"
},
"weight": {
"unit": "GRAM",
"value": 250
},
"insuredValue": {
"value": 44,
"unit": "USD"
},
"isHazmat": false,
"packageClientReferenceId": "PPEI-4326495734098",
"items": [
"description": "Description of the item1",
"itemIdentifier": “ASIN-Example-B08C61BCFP",
"quantity": 1,
"isHazmat": false,
"directFulfillmentItemIdentifiers": {
"lineItemID": "11312",
"pieceNumber": "1"
}
},
{
"description": "Description of the item2",
"itemIdentifier": " ASIN-Example-B80C91BBFG",
"quantity": 1,
"isHazmat": false,
"directFulfillmentItemIdentifiers": {
"lineItemID": "12352",
"pieceNumber": "1"
 }
}
]
}
],
"channelDetails": {
"channelType": "AMAZON",
"amazonShipmentDetails": {
"shipmentId": "XO732BB9"
}
},
"labelSpecifications": {
"format": "ZPL",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"dpi": 203,
"pageLayout": "string",
"needFileJoining": true,
"requestedDocumentTypes": [
"LABEL"
]
}
}
Response
A successful response includes the following elements:
Name Description Required
shipmentID A unique identifier for a shipment that will be
generated by Amazon. Yes
Type: String
packageDocumentDetails Post-Purchase details of each package. This is a list Yes
of packages created within a single shipment and
includes the carrier tracking ID.
Type: Package Document Details

Response example:
HTTP/1.1 200 OK

"payload": {
{
"shipmentId": "445454-3232-3232",
"packageDocumentDetailList": [
{
"packageClientReferenceId": "ASUSDI-45343854",
"trackingId": "T1234567",
"packageDocuments": [
{
"type": "LABEL",
 "format": "ZPL",
"contents":
"iVBORw0KGgoAAAANALiAXEAmIBsYBYALGAWEAsIBYQC4gFxAKIBcQCYgGxgFhALIBYQCwgFhALiA
XEAmIByv4PwWms3AV97VoAAAAASUVORK5CYII="
}
]
}
}

Tutorial: Retrieve previously generated shipment documents

This tutorial shows how to get previously generated shipping documents for a single given package. Use
the getShipmentDocument operation to retrieve previously generated shipping documents for a given
single package; e.g reprinting a label. The Input is the Amazon Shipping generated Shipment ID and the
clientReferenceID, which is a client generated field used to identify the package within a single shipment
during the purchase operation.

NOTE: This operation will only return shipping documents in the original requested document format.
For instance, if you requested a PNG label for a package in the original Purchase Shipment call, calling
this API will return the original PNG label. If you wish to generate a different document type from what
was originally created, please cancel the Shipment and generate a new shipment with the desired
document type.

NOTE: This operation does is unavailable for Direct Fulfillment shipments.

Step 1. Retrieve previously generated shipping documents

Call the getShipmentDocuments operation for a shipment using the following query parameters.

Query Parameter:
Name Description Required
shipmentID Shipment Id returned as part of the Purchase Yes
Label call.
Type: String
packageClientReferenceID Client Provided ReferenceID for a given Yes
package used during the purchase shipment
operation.
Type: String
format File Format of the document. Should be one of Yes
the supported formats returned in GetRates
response. Possible options:
- PDF
- PNG
- ZPL
Type: String

Request example:
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipment/445454-
3232-3232/documents?packageClientReferenceId=ASUSDI-45343854&format=PNG

HTTP/1.1
Authorization: Bearer <token>

Response
A successful response includes the following elements:
Shipment Document Response
Name Description Required
shipmentId Returns the unique shipmentId for a given shipment.
Yes
Type: String
packageDocumentDetail Container for package document details.
Yes
Type: Package Document
trackingID Carrier generated identifier used to track a single
package. No
Type: String

Response example:

HTTP/1.1 200 OK
{
"payload": {
"shipmentId": "445454-3232-3232",
"packageDocumentDetail": {
"packageClientReferenceId": "ASUSDI-45343854",
"trackingId": "T1234567",
"packageDocuments": [
{
"type": "LABEL",
"format": "PNG",
"contents": "sdioadaiosfhdodsaiufhouafhoudfhdouahfac=="
}
]
}
}

Tutorial: Track a shipment

This tutorial shows how to track previously created shipment. The getTracking operation provides
tracking information for all Amazon Shipping packages, including the most recent status and package
status history.

NOTE: This operation will only return a response for packages shipped with Amazon Shipping currently,
and is unavailable for Direct Fulfillment shipments. To track Amazon orders shipped with another
carrier, please call the external carriers tracking API directly. You will only be able to retrieve Amazon
Shipping Tracking details up to 45 days after the shipment creation date. After this period, only the last
tracking status will be returned for a given trackingID.
Step 1. Track a shipment

Call the getTracking operation for a shipment using the following query parameters.

Query Parameters:
Name Description Required
carrierID CarrierID for a trackingID (passed in the Rate Yes
response).
Type: String
trackingID TrackingID for a given package returned in the Yes
purchase shipment response.
Type: String

Request example:
POST https://sellingpartnerapi-
eu.amazon.com/shipping/v2/tracking?carrierId=AMZN_US&trackingId=23AA47
DE2B3B6

Authorization: Bearer <token>

Response
A successful response includes the following elements:
Name Description Required
trackingId TrackingId for the container for which tracking
events are requested. Yes
Type: String
eventHistory A list of all tracking events present for the requested
container. The list will contain events in sorted order
of eventTime; the event with most recent time being
the first event in the list and the event with latest Yes
event time being the last element in the list.
Type: List of Events
promisedDeliveryDate Promised delivery date for the container at the time
of the scan. This will be a String representing the
date in ISO-8601 format. Yes
Type: String (date-time)
summary High-level status of the tracked shipment. Possible
options:
- PRE_TRANSIT: package has been created
but has not been picked up.
- IN_TRANSIT: package has been picked up
and is in transit.
- DELIVERED: package has been delivered Yes
successfully.
- LOST: package is lost.
- OUT_FOR_DELIVERY: package is out for
delivery.
- REJECTED: package has been rejected by
the recipient.
 - UNDELIVERABLE: package was
undeliverable.
- DELIVERY_ATTEMPTED: delivery was
attempted to the recipient location, but was
not delivered.
- PICKUP_CANCELLED: indicate that pickup
was cancelled for the package.
Type: String

Response example:
HTTP/1.1 200 OK

"payload": {
"trackingId": "23AA47DE2B3B6",
"eventHistory": [
{
"eventCode": "READY_FOR_RECEIVE",
"location": {
"postalCode": "91754",
"city": "Monterey Park",
"stateOrRegion": "California",
"countryCode": "US"
},
"eventTime": "2019-12-11T07:09:05.513Z"
}
],
"promisedDeliveryDate": "2019-12-12T13:09:05.513Z",
"summary": {
"status": "PRE_TRANSIT"
}
}

Tutorial: Cancel a shipment

This tutorial shows how to cancel a previously created shipment. The cancelShipment operations cancels
a shipment that has not been picked up. If the shipment has already been picked up, you will not be able
to cancel it.

NOTE: If you have not purchased a label (successfully completed a Purchase Label call) no cancellation is
necessary. For Carriers other than Amazon Shipping, cancellation windows vary. Please see Seller
Central help for carrier specific cancellation/ refund windows. This is unavailable for Direct Fulfillment
shipments.

Step 1. Cancel a shipment

Call the cancelShipment operation for a shipment with the following request query parameter.
 Name Description Required
shipmentID A unique identifier for a shipment. Yes
Type: String

Request example:
PUT https://sellingpartnerapi-
eu.amazon.com/shipping/v2/shipments/amzn1.sid.96267892621710.100/cance
l

HTTP/1.1

Authorization: Bearer <token>

A successful response includes the following:

Empty 200 response indicated successful cancellation.

Response example:

HTTP/1.1 200 OK
{}

Shipping data types

The following data types are used in the request and response elements of the Shipping APIs.

Datatype Description
Address The designation for a specific location.
The parcel that will be shipped through an available shipping service
Package offering.
Dimension A set of measurements for the package.
Weight The specific weight for a package.
Currency Amount and currency defined in the ISO 4217 standard format.
Item Details pertaining to the specific object being shipped.
Channel Details Specifies channel package originates from.
Direct Fulfillment Item Identifiers Additional item identifiers for a direct fulfillment order shipment.
Amazon Order Details Specifies the Amazon order fulfilled by the package.
Amazon Shipment Details Specifies the Amazon shipment details for a direct fulfillment order.
Rate Details of a shipping service offering.
Supported Document Specifications Details of available supported documentation for a service offering.
Document Size Dimension details for a document.
Print Options Formats options available for a label.
Requested Document Specification Document specification requested in purchase.
Supported Document Detail Document specification that is supported for a service offering
Available Value Added Service Group Value Added Services that is available for a shipping service offering.
Value Added Service Details on a specific additional service.
 Ineligible Rates Service options that are unavailable for the package.
Ineligible Reason Describes the ineligibility of a ship option.
Requested Value Added Service Value Added Services that is to be applied for a shipping service
purchase.
Post purchase detail of the package that will be shipped through a
Package Document Detail shipping service.
Package Document Document for a specific package.
Promise Time windows promised for pickup and delivery events.
Time Window Time duration used to specify the interval of an event.
Event A specific tracking update.
Location The location of the package at the tracked event.

Address
The designation for a specific location.
Address
Name Description Required
The name of the person, business or institution at an address.
Yes
name Type: String
First line of the address. Yes
addressLine1 Type: String
Additional address information, if required.
No
addressLine2 Type: String
Additional address information, if required.
No
addressLine3 Type: String
Name of the business or institution associated with address.
No
companyName Type: String
The city where the person, business or institution is located.
Yes
city Type: String
The postal code of the address. Contains a series of letters or
digits or both, sometimes including spaces or punctuation. Yes
postalCode Type: String
The two-digit country code. In ISO 3166-1 alpha-2 format.
Yes
countryCode Type: String
The state or region where the person, business or institution is
located. This is required for US addresses only. Yes
stateOrRegion Type: String
The email address of the person, business or institution
associated with the address. No
email Type: String
The phone number of the person, business or institution located
at that address. No
phoneNumber Type: String
Package
The parcel that will be shipped through an available shipping service offering.
Package
Name Description Required
The length, width, height, and weight of the package.
Values cannot be 0 or null. Yes
dimensions Type: Dimension
weight First line of the address. Yes
Type: Weight
insuredValue Container for the insured value of the package.
Yes
Type: Currency
A list of the items in the container. This is required for
Amazon orders and international shipments. Conditional
items Type: Item
If the package contains hazmat items this must be
marked as [True] (If left blank, value defaults to false). No
isHazmat Type: Boolean
Client generated field used to identify a specific package
within a shipment. This is a client reference field, which
Yes
must be unique within a single shipment.
packageClientReferenceId Type: String

Dimension
A set of measurements for the package.
Dimension
Name Description Required
length The Length of a package (the longest side) Yes
Type: number
width The width of package. Yes
Type: number
height The height of package. Yes
Type: number
unit The unit being used for dimensions. Values accepted are CM or Yes
IN.
Type: String (enum)
Weight
The specific weight for a package.
Weight
Name Description Required
The unit used to measure package weight. Possible values:
- KG
- G Yes
- LBS
- OZ
unit Type: String
The actual weight of the package.
Yes
value Type: number

Currency
Amount and currency defined in the ISO 4217 standard format.
Currency
Name Description Required
Currency amount value.
Yes
value Type: number
ISO 4217 currency code.
unit Yes
Type: String

Item
Details pertaining to the specific object being shipped.

Item
Name Description Required
Object for the value of the item being shipped.
No
itemValue Type: Currency
Human readable description of the item being shipped.
No
description Type: String
Unique way to identify the item. The ASIN being shipped
must be passed in this field for Amazon orders. Cond.
itemIdentifier Type: String
quantity The quantity of the items of this type in the package.
Yes
Type: Integer
weight The weight of the specific item in the package.
Yes
Type: Weight
Indicates whether an item is hazmat or not. Defaults to false.
No
isHazmat Type: Boolean
List of unique serial numbers to match against an Amazon
package to guarantee non-fraudulent items. The number of
serial numbers in the list must be less than or equal to the Cond.
serialNumbers quantity of items being shipped in the request. Only
applicable when channel source is Amazon.
 Type: list of Strings
Item details specific for Direct Fulfillment shipments. This
directFulfillmentIt object is required if shipment is a direct fulfillment order.
Cond.
emIdentifiers Type: directFulfillmentItemIdentifiers

Direct Fulfillment Item Identifiers

Additional item identifiers for a direct fulfillment order shipment.
Direct Fulfillment Item Identifiers
Name Description Required
Unique identifier for an Item provided by the client for Direct
Fulfillment shipments. This is only populated for Direct
Fulfillment multi-piece shipments and mandatory if vendor
wants to change the configuration of packages in which the Yes
lineItemID purchase order is shipped. This is the instruction provided
from Direct Fulfillment along with Order Fulfilment.
Type: String
Unique identifier for an Item provided by the client for Direct
Fulfillment shipments. This is only populated for Direct
Fulfillment shipments if single line item has multiple pieces
pieceNumber and will be defaulted to 1 if not provided. No
Type: String

Channel Details
Specifies channel package originates from.
Channel Details
Name Description Required
String to denote source of shipment.
Possible values: “Amazon”, “External”)
• “Amazon” must be selected for Amazon orders
Yes
(including Direct Fulfillment).
channelType • “External” may be used for all other shipments.
Type: String
Object to pass details about the Amazon order details if Cond. (required only
amazonOrderDetails order originates from Amazon. for Amazon order)
Type: Amazon Order Details
Object to pass details about the shipment details if order Cond. (required only
originates from a Direct Fulfillment. for Direct Fulfillment
amazonShipmentDetails Type: Amazon Shipment Details shipment)

Amazon Order Details

Specifies the Amazon Order fulfilled by the package.
 Amazon Order Details
Name Description Required
This is the Amazon Order ID associated to the Amazon order
fulfilled by this shipment. Yes
orderId Type: String

Amazon Shipment Details

Specifies the Amazon Shipment Details for a direct fulfillment order shipment.
Amazon Shipment Details
Name Description Required
This attribute is required for a Direct Fulfillment shipment. This is
the Encrypted Shipment ID. Yes
shipmentId Type: String

Rate
Details of a shipping service offering.
Rate
Name Description Required
rateId An identifier for the rating/offering provided Yes
by service
Type: String
carrierId The Id of the carrier offering a rate for a given Yes
shipment.
Type: String
carrierName Carrier name for the service offering returned. Yes
Type: String
serviceId An identifier for the shipping service provided Yes
by service.
Type: String
serviceName The type of service offered (e.g Amazon Yes
Shipping Ground, USPS First Class, etc).
Type: String
billedWeight The weight billed for the rate. No
Type: Weight
totalCharge The total charge for the rate. Yes
Type: Currency
supportedDocumentSpecifications List of supported documentation No
specifications.
Type: Supported Documentation
Specifications
availableValueAddedServiceGroups List of available value added service groups. No
Type: Available Value Added Service Group
requiresAdditionalInputs This Boolean flag indicates if the shipping Yes
offering requires additional inputs to be
 passed for purchase. GetAdditionalInputs API
should be invoked if this value is true.
Type: Boolean

Supported Document Specification

Details of available supported documentation for a service offering.
Supported Document Specifications
Name Description Required
format File Format of the document. Eg: PDF, PNG or Yes
ZPL.
Type: String
Size Size of the request documentation. (i.e 4x6 in) Yes
Type: Document Size
printOptions Object to contain list of print options Yes
Type: List of print options
serviceId An identifier for the shipping service provided Yes
by service.
Type: String

Document Size
Dimension details for a document.
Document Size
Name Description Required
width Width of the document to be printed. Yes
Type: number
length Length of the document to be printed. Yes
Type: number
unit Unit for the height and width. Yes
Type: String

Print Options
Formats options available for a label.
 Print Options
Name Description Required
supportedDPIs List of supported DPIs for a given shipping Yes
service.
Type: Integer
supportedPageLayouts Indicator for position of the document to be Yes
printed.
Type: String
supportedFileJoiningOptions Indicator whether files should be stitched Yes
together or returned separately. Defaults to
false.
Type: Boolean
supportedDocumentDetails Document Types that are supported for a Yes
given shipping service.
Type: Supported Document Detail

Requested Document Specification

The documents specifications requested in purchase.
 Requested Document Specification
Name Description Required
format File Format of the document. Possible values Yes
are:
- PNG
- ZPL
- PDF
Note: PDF is unavailable for Direct Fulfillment
shipments.

Type: String (enum)

size Size of the request documentation. (i.e 4x6 in) Yes
Type: Document Size
dpi Dots per Inch (DPI) value used in printing No
Type: String
pageLayout Indicator for position of the document to be No
printed.
Type: String
needFileJoining Indicator whether files should be stitched Yes
together or returned separately. Defaults to
false.
Type: Boolean
requestedDocumentTypes The type of shipping document. Yes
Possible values are:
- PACKSLIP
- LABEL
- RECEIPT
- CUSTOM_FORM
Note: Only ‘LABEL’ is valid for Direct
Fulfillment shipments.

Type: String (enum)

Supported Document Detail

Document specification that is supported for a service offering.
Supported Document Detail
Name Description Required
name Name of the supported document. Possible Yes
values are:
- PACKSLIP
- LABEL
- RECEIPT
- CUSTOM_FORM
Type: String
isMandatory Indicates whether Supported Document Type Yes
is mandatory.
Type: Boolean
Available Value Added Service Groups
Value Added Services that is available for a shipping service offering.
Available Value Added Service Group
Name Description Required
name ID for the group of Value Added Services. Yes
Type: String
groupDescription Friendly name describing the group (e.g. Yes
“delivery confirmation”).
Type: String
isRequired Indicates whether a VAS is required for a given Yes
rate (eg: shipping service requires signature
on delivery).
Type: String
valueAddedServices Details of a specific VAS. Yes
Type: Value Added Service

Value Added Service

Details on a specific additional service.
Value Added Service
Name Description Required
id ID of a given VAS. Yes
Type: String
name Name of a given VAS. Yes
Type: String
Cost Container for individual VAS cost. Yes
Type: Currency
valueAddedServices Details of a specific VAS. Yes
Type: Value Added Service

Ineligible Rates
Service options that are unavailable for the package.
Ineligible Rates
Name Description Required
serviceId An identifier for the shipping service provided Yes
by service.
Type: String
serviceName The type of service offered (e.g Amazon Yes
Shipping Ground, USPS First Class, etc).
Type: String
 carrierName Carrier name for the service offering returned. Yes
Type: String
carrierId The Id of the carrier offering a rate for a given Yes
shipment.
Type: String
ineligibilityReasons Reason rate is ineligible for a given Yes
shipment request.
Type: Ineligible Reason

Ineligible Reason
Describes the ineligibility of a ship option.
Ineligible Reason
Name Description Required
code Code for the ineligibility reason Yes
Type: String
message Reason rate is ineligible for a given shipment Yes
request.
Type: String

Requested Value Added Service

Value Added Services that is to be applied for a shipping service purchase.
Requested Value Added Service
Name Description Required
id Identifier of the selected value added service. Yes
The ID should be among the list of IDs
returned in GetRates call, else purchase will
fail.
Type: String

Package Document Details

Post purchase detail of the package that will be shipped through a shipping service.
Package Document Details
Name Description Required
packageClientReferenceId Client-provided unique identifier for a package
within a shipment. Yes
Type: String
packageDocuments List of documents associated with a package. Yes
Possible options:
- Label
- Packslip
- Receipt
- Custom Form
Type: Package Document
promise Promised pickup and delivery time windows for a Yes
given shipment.
 Type: Promise

Package Document
Document for a specific package.
Package Document
Name Description Required
type Type of Document being returned. Possible options:
- PACKSLIP
- LABEL
Yes
- RECEIPT
- CUSTOM_FORM
Type: String
format File format of document (e.g. PDF, ZPL, PNG). Possible Yes
options:
- PDF
- ZPL
- PNG
Type: String
contents BASE64 encoded file contents. Yes
Type: String

Promise
Time windows promised for pickup and delivery events.
Promise
Name Description Required
deliveryWindow Time duration object used to describe the promised
delivery window for a given shipment. Yes
Type: TimeWindow
pickupWindow Time duration object used to describe the promised Yes
pickup window for a given shipment.
Type: TimeWindow

Time Window
Time duration used to specify the interval of an event.
Time Window
Name Description Required
startTime Start of a delivery window.
Yes
Type: String (date-time)
endTime End of a delivery window. Yes
Type: String (date-time)

Event
A specific tracking update.
Event
Name Description Required
 eventCode Denotes a tracking event for the container. These
are carrier scans applied to a package. Possible
options:
- READY_FOR_RECEIVE: package has been
created and is ready for pickup the shippers
location. This is a pre-transit status event
code.
- PICKUP_DONE: package has been picked up
by the carrier and is in transit within the
carrier network.
- DELIVERED: package has been delivered.
- DEPARTED: package has departed from a
particular location in carrier network.
- DELIVERY_ATTEMPTED: delivery was Yes
attempted but unsuccessful.
- LOST: package is lost.
- OUT_FOR_DELIVERY: package is out for
delivery.
- ARRIVED_AT_CARRIER_FACILITY: package is
in transit and has been received at a carrier
location.
- REJECTED: package was rejected by the
recipient.
- UNDELIVERABLE: package is undeliverable.
- PICKUP_CANCELLED: pickup scheduled for
the package was cancelled.
Type: String
location Denotes the location at which the scan event was
generated on the container. Yes
Type: Location
eventTime Denotes the time at which the scan event was
generated on the package. This will be a String
Yes
representing the time in ISO-8061 format
Type: String (date-time)

Location
The location of the package at the tracked event.
Location
Name Description Required
stateOrRegion The state, county or region where the person,
business or institution is located. Yes
Type: String
city The city or town where the person, business or
institution is located. Yes
Type: String
countryCode The two digit country code. Follows ISO 3166-1
alpha-2 format. Yes
Type: String
postalCode The postal code of that address. It contains a series
of letters or digits or both, sometimes including
spaces or punctuation. Yes
Type: String