Shipping API v2 Use Case Guide
This document provides an overview of how to accomplish specific use cases with the Shipping APIs such as how to create and track shipments using the Amazon Shipping APIs.
API Version: v2
What is the Shipping API?
The Amazon Shipping API (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. See the Shipping API Reference for details about operations and associated data types and schemas.
Workflow for creating a shipment
Creating a shipment is a multi-step process that includes calls to the Shipping API. Here's the recommended workflow for creating a shipment.
-
Call the getRates operation to get a set of eligible rate for the shipment.
Amazon returns a set of eligible rates for the shipment.
-
(Conditional) Call the getAdditionalInputs operation if directed to do so by the getRates operation to discover additional data required to purchase a shipment. This step is required for international shipments.
-
Call the purchaseShipment operation with any required additional inputs to create a shipment.
Amazon creates a shipment based on the information provided.
Alternatively, vendors can purchase the best fit ship option for the package by calling the direct purchase shipment operation. This is only available for Direct Fulfillment program orders currently.
- Call the directPurchaseShipment operation to create a shipment.
Once a shipment is created, the Shipping API 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 for a purchased shipment.
-
Call the getShipmentDocuments operation to return documents associated with a package in the shipment.
-
Call the cancelShipment operation to cancel a purchased shipment.
Here is the recommended workflow for creating a shipment:
Here is the recommended workflow for creating a vendor own carrier Direct Fulfillment shipment:
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 shipping 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 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.
-
Rate. A collection of shipping service name, pickup window, promised delivery date, base cost and eligible value-added services available for a given shipping service.
-
Value Added Service (VAS). A service added to a base shipping rate. This can include services such as insurance, or signature on delivery, for example. The getRates operation returns all available VAS's represented as individual VAS ID's for a given shipping service, which you can then request when calling the purchaseShipment operation.
-
Document Types. A variety of documentation produced to facilitate the shipment. The available document types are Label, Packing slip, Receipt, Customs Form.
-
Off-Amazon. Identifies a shipment which is not generated on Amazon Marketplace.
-
On-Amazon. Identifies a shipment which is generated on Amazon Marketplace.
-
Vendor's Own Carrier (VOC). Identifies a vendor enrolled in the Vendor's Own Carrier program. A VOC vendor uses their own carrier for shipment delivery and does not use Amazon carriers.
The Shipping API supports the following operations:
Operation |
HTTP Method |
Path | Description |
getRates | POST | /shipping/v2/shipments/rates | Returns the list of shipping service offerings and optional value-added services available for a given shipment. |
purchaseShipment | POST | /shipping/v2/shipments | Purchases and returns a label based on the given rate. |
directPurchaseShipment [Paused] | POST | /shipping/v2/shipments/directPurchase | Purchases and returns a label based on the best service fit. Currently, this feature is paused until further development. |
getAdditionalInputs | GET | /shipping/v2/shipments/additionalInputs/schema | When additional inputs are required for a given shipping service (as indicated in the getRates response), this API returns the additional field schema required to purchase the specified rate. |
getShipmentDocuments | GET | /shipping/v2/shipments/{shipmentID}/documents | Retrieves a shipping label or other shipping documents for a previously created shipment. |
getTracking | GET | /shipping/v2/tracking | Gets the tracking status for packages shipped with Amazon. |
cancelShipment | PUT | /shipping/v2/shipments/{shipmentId}/cancel | Cancels a previously created label that has not been picked up. |
Tutorial: Purchase a shipment from a rate
This tutorial shows how to get rates for a shipment, get any additional inputs when required, and purchase a shipment.
Prerequisites
To complete this tutorial, you will need:
-
Enrollment in an eligible program.
-
A selling-partner account if you are an Amazon seller or are working with an Amazon seller to create and manage shipments.
-
Authorization from the selling-partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.
Step 1. Get rates for a shipment
Step 2. Discover required additional inputs for a shipment
Step 1. Get rates for a shipment
Getting the rates for a shipment returns the eligible shipping services for a given address, package specifications and/or pickup slot, and provides a delivery promise consisting of a pickup time range and a delivery window. If a pickup slot was not specified in the request by providing a shipDate value, the current date will be used to return the next eligible slot.
If you are fulfilling an Amazon order, ensure the following details are provided in the getRates request:
- The Amazon order number must be provided in the channel details.
Amazon Order
"channelDetails": {
"channelType": "AMAZON",
"amazonOrderDetails": {
"orderId": "912-1061508-5843035"
}
}
- The Order Item ID should be sent in the itemIdentifier tag. Refer the guide for getOrder and getOrderItems to fetch the Orderitemid.
Amazon Order Item ID
"items": [
{
"quantity": 1,
"itemValue": {
"unit": "EUR",
"value": 10
},
"weight": {
"unit": "KILOGRAM",
"value": 0.431
},
"description": "COSMETICS",
"itemIdentifier": "Orderitemid",
"isHazmat": false
}
],
NOTE: At this time, each shipment is limited to a single package. 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 should the single package limitation be removed.
To get the rates for a shipment:
Call the getRates operation, passing the following parameters:
Request parameters
Request body
Name | Description | Required |
---|---|---|
shipTo |
The address where the shipment will be delivered. For Amazon orders, shipTo information is pulled directly from the Amazon order.
Type: Address |
Conditional |
shipFrom |
The address where the package will be picked up.
Type: Address |
Yes |
returnTo |
The address where the package will be returned if it cannot be delivered.
Type: Address |
No |
shipDate |
The ship date and time (the requested pickup). This defaults to the current date and time.
Type: string (date-time) |
No |
packages |
A list of packages to be shipped and package details.
Type: PackageList |
Yes |
valueAddedServices |
A collection of supported value-added services.
Type: ValueAddedServiceDetails |
No |
taxDetails |
A list of tax detail information.
Type: TaxDetailList |
No |
channelDetails |
Shipment source channel related information.
Type: ChannelDetails |
Yes |
Request header parameter
Name | Description | Required |
---|---|---|
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Off-Amazon request example
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: AmazonShipping_UK
{
"shipTo": {
"name": "Customer Name",
"addressLine1": "12, Meersbrook Park Road",
"addressLine2": "Meersbrook",
"postalCode": "OX15 6NA",
"city": "SHEFFIELD",
"stateOrRegion": "SHEFFIELD",
"countryCode": "GB",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "Shipper Name",
"addressLine1": "Plane Tree Crescent",
"postalCode": "S8 9FP",
"city": "Feltham",
"stateOrRegion": "Feltham",
"countryCode": "GB",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"shipDate": "2022-03-23T09:00:00Z",
"packages": [
{
"dimensions": {
"length": 3.14,
"width": 3.14,
"height": 3.14,
"unit": "INCH"
},
"weight": {
"unit": "KILOGRAM",
"value": 3.14159
},
"items": [
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.14159
}
},
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.14159
}
}
],
"insuredValue": {
"unit": "GBP",
"value": 29.98
},
"packageClientReferenceId": "<Use_Order_ID>"
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
Response
A successful response includes the following:
Name | Description | Schema |
---|---|---|
payload | The payload for the getRates operation. | GetRatesResult |
Off-Amazon response example
{
"payload": {
"requestToken": "amzn1.94b6c96d-68ab-4fe6-a278-b85835b7e475",
"rates": [
{
"rateId": "e1b7cf2d1516d8c5343a087e10a5a2261ff36b83bdb5a91c6ce51b19586ed9861507200580943",
"carrierId": "AMZN_UK",
"carrierName": "Amazon Shipping",
"serviceId": "SWA-UK-PRIME-PREM",
"serviceName": "Amazon Shipping One Day",
"promise": {
"pickupWindow": {
"startTime": "2017-10-13T19:51:23Z",
"endTime": "2017-10-13T19:51:23Z"
},
"deliveryWindow": {
"startTime": "2017-10-14T19:51:23Z",
"endTime": "2017-10-14T19:51:23Z"
}
},
"supportedDocumentSpecifications": [
{
"format": "PNG",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"DEFAULT"
],
"supportedFileJoiningOptions": [
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
},
{
"format": "ZPL",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"DEFAULT"
],
"supportedFileJoiningOptions": [
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
},
{
"format": "PDF",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"DEFAULT"
],
"supportedFileJoiningOptions": [
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
}
],
"availableValueAddedServiceGroups": null,
"totalCharge": {
"unit": "GBP",
"value": 4.76
},
"billedWeight": {
"value": 1,
"unit": "KILOGRAM"
},
"requiresAdditionalInputs": false
},
{
"rateId": "e9305a93989acce639f625842b64708f9daaf73bb87cc0cbf11f31f3c944b9761507200580943",
"carrierId": "AMZN_UK",
"carrierName": "Amazon Shipping",
"serviceId": "SWA-UK-ECON",
"serviceName": "Amazon Shipping Standard",
"promise": {
"pickupWindow": {
"startTime": "2017-10-13T19:51:23Z",
"endTime": "2017-10-13T23:51:23Z"
},
"deliveryWindow": {
"startTime": "2017-10-18T19:51:23Z",
"endTime": "2017-10-18T19:51:23Z"
}
},
"supportedDocumentSpecifications": [
{
"format": "PNG",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"DEFAULT"
],
"supportedFileJoiningOptions": [
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
},
{
"format": "ZPL",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"DEFAULT"
],
"supportedFileJoiningOptions": [
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
},
{
"format": "PDF",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedPageLayouts": [
"DEFAULT"
],
"supportedFileJoiningOptions": [
false
],
"supportedDocumentDetails": [
{
"name": "LABEL",
"isMandatory": true
}
]
}
]
}
],
"availableValueAddedServiceGroups": null,
"totalCharge": {
"unit": "GBP",
"value": 3.72
},
"billedWeight": {
"value": 1,
"unit": "KILOGRAM"
},
"requiresAdditionalInputs": false
}
],
"ineligibleRates": []
}
}
On-Amazon request example
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: AmazonShipping_UK
{
"shipTo": {
"name": "James Martin - New Country Company",
"addressLine1": "12, Meersbrook Park Road",
"addressLine2": "Meersbrook",
"postalCode": "OX15 6NA",
"city": "SHEFFIELD",
"stateOrRegion": "SHEFFIELD",
"countryCode": "GB",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "A1",
"addressLine1": "Plane Tree Crescent",
"postalCode": "S8 9FP",
"city": "Feltham",
"stateOrRegion": "Feltham",
"countryCode": "GB",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"packages": [
{
"dimensions": {
"length": 12.99,
"width": 9.45,
"height": 5.91,
"unit": "INCH"
},
"weight": {
"unit": "KILOGRAM",
"value": 0.5
},
"items": [
{
"itemValue": {
"unit": "GBP",
"value": 13.99
},
"description": "Ring Made with Swarovski Zirconia for Women in Platinum Plated 925 Sterling Silver Engagement Gemstone Jewellery Size T",
"itemIdentifier": "69783225326731",
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 0.01
}
}
],
"insuredValue": {
"unit": "GBP",
"value": 13.99
},
"packageClientReferenceId": "SW17271398"
}
],
"channelDetails": {
"channelType": "AMAZON",
"amazonOrderDetails": {
"orderId": "026-1671542-1523528"
}
}
}
On-Amazon response example
{
"payload": {
"ineligibleRates": [
{
"carrierId": "CHINA_POST",
"carrierName": "China Post",
"ineligibilityReasons": [
{
"code": "UNKNOWN",
"message": "It is not an eligible ship method for this order."
},
{
"code": "UNKNOWN",
"message": "The Carrier Terms and Conditions were not accepted"
}
],
"serviceId": "CHINA_POST_AIRMAIL",
"serviceName": "China Post Ordinary Airmail"
}
],
"rates": [
{
"availableValueAddedServiceGroups": [
{
"groupDescription": "Pickup",
"groupId": "VAS_GROUP_ID_PICKUP",
"isRequired": true,
"valueAddedServices": [
{
"cost": {
"unit": "GBP",
"value": 0
},
"id": "CARRIER_PICKUP_CHARGE",
"name": "Carrier Pickup"
}
]
}
],
"carrierId": "AMZN_UK",
"carrierName": "Amazon Shipping",
"promise": {
"deliveryWindow": {
"endTime": "2021-10-20T19:00:00Z",
"startTime": "2021-10-20T19:00:00Z"
},
"pickupWindow": {
"endTime": "2021-10-18T17:30:00Z",
"startTime": "2021-10-18T17:00:00Z"
}
},
"rateId": "0193bfed-6bc1-449c-8504-02a431732d55",
"requiresAdditionalInputs": false,
"serviceId": "prime-premium-uk-mfn",
"serviceName": "Amazon Shipping One-Day Tracked",
"supportedDocumentSpecifications": [
{
"format": "PNG",
"printOptions": [
{
"supportedDPIs": [],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
true
],
"supportedPageLayouts": [
"LEFT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
},
{
"format": "ZPL",
"printOptions": [
{
"supportedDPIs": [
300
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
true
],
"supportedPageLayouts": [
"LEFT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
}
],
"totalCharge": {
"unit": "GBP",
"value": 2.53
}
}
],
"requestToken": "amzn1.rq.e15983c1-3ab7-40b5-bd9f-46cb56605bc7.101"
}
}
Off-Amazon request example with tax details (India)
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: AmazonShipping_IN
{
"shipTo": {
"name": "Pavan",
"addressLine1": "Shop No 4",
"addressLine2": "Sec No 11",
"postalCode": "500032",
"city": "Hyderabad",
"countryCode": "IN",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "A1",
"addressLine1": "1141,Maker Chambers V",
"addressLine2": "J Bajaj Road, Nariman Point",
"postalCode": "500032",
"city": "Hyderabad",
"countryCode": "IN",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"packages": [
{
"dimensions": {
"length": 3.14,
"width": 3.14,
"height": 3.14,
"unit": "INCH"
},
"weight": {
"unit": "KILOGRAM",
"value": 3.14159
},
"items": [
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.14159
},
"isHazmat": false
},
{
"quantity": 1,
"weight": {
"unit": "KILOGRAM",
"value": 1.14159
}
}
],
"insuredValue": {
"unit": "INR",
"value": 29.98
},
"isHazmat": false,
"packageClientReferenceId": "abcd"
}
],
"valueAddedServices": {
"collectOnDelivery": {
"amount": {
"value": 10,
"unit": "INR"
}
}
},
"taxDetails": [
{
"taxType": "GST",
"taxRegistrationNumber": "87878"
}
],
"channelDetails": {
"channelType": "EXTERNAL"
}
}
Off-Amazon response example (India)
{
"payload": {
"ineligibleRates": [],
"rates": [
{
"availableValueAddedServiceGroups": [
{
"groupId": "CollectOnDelivery",
"isRequired": true,
"valueAddedServices": [
{
"id": "CollectOnDelivery",
"name": "CollectOnDelivery"
}
]
}
],
"billedWeight": {
"unit": "KILOGRAM",
"value": 3.1
},
"carrierId": "ATS",
"carrierName": "Amazon Shipping",
"promise": {
"deliveryWindow": {
"endTime": "2021-12-06T18:29:00Z",
"startTime": "2021-12-05T18:30:00Z"
},
"pickupWindow": {
"endTime": "2021-12-02T10:45:00Z",
"startTime": "2021-12-02T08:30:00Z"
}
},
"rateId": "d62d932beec4bad24ea4990a5aad657096efc4f363449e78f061215b000318d61638430994664",
"requiresAdditionalInputs": false,
"serviceId": "SWA-IN-OA",
"serviceName": "Amazon Shipping Standard",
"supportedDocumentSpecifications": [
{
"format": "PNG",
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
false
],
"supportedPageLayouts": [
"DEFAULT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
},
{
"format": "ZPL",
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
false
],
"supportedPageLayouts": [
"DEFAULT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
},
{
"format": "PDF",
"printOptions": [
{
"supportedDPIs": [
300,
203
],
"supportedDocumentDetails": [
{
"isMandatory": true,
"name": "LABEL"
}
],
"supportedFileJoiningOptions": [
false
],
"supportedPageLayouts": [
"DEFAULT"
]
}
],
"size": {
"length": 6,
"unit": "INCH",
"width": 4
}
}
],
"totalCharge": {
"unit": "INR",
"value": 151
}
}
],
"requestToken": "amzn1.rq.99200470481323.100"
}
}
Step 2. Discover required additional inputs for a shipment
The requiresAdditionalInputs
property in the response to the getRates
operation indicates whether you must provide additional inputs to purchase the shipping service that corresponds to a rate. When true, you must call the getAdditionalInputs
operation to return the JSON schema to use when providing the additional information. You provide the additional inputs when you call the purchaseShipment
operation to purchase the shipping service.
You use the getAdditionalInputs
operation to understand what additional inputs are required. This is a required step for international shipments. The response returns the schema you must use to provide the additional inputs when you call the purchaseShipment
operation. You can also use the information in the schema to inform your building of dynamic forms for your end user to use to provide the additional information required.
NOTE: These fields may change as customs/regulatory rules change in different geographies, so we recommend that you do not cache/hardcode these fields for future purchase shipment calls.
To get the JSON schema for the additional inputs required:
Call the getAdditionalInputs operation, passing the following parameters:
Request parameters
Query parameters
Name | Description | Required |
---|---|---|
requestToken | The request token returned in the response to the getRates operation.
Type: string |
Yes |
rateId | The rate identifier for the shipping offering (rate) returned in the response to the getRates operation.
Type: string |
Yes |
Request header parameter
Name | Description | Required |
---|---|---|
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Request example
GET https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/additionalInputs/schema?requestToken=amzn1.rq.5cbe8664-285e-4bd5-8a70-db2ed9ba127e.101&rateId=9559ad41-c9da-12b3-abc9-5684e6a76be8
Response
A successful response includes the following:
Name | Description | Schema |
---|---|---|
payload | The JSON schema to use to provide additional inputs when required to purchase a shipping offering. | GetAdditionalInputsResult |
Response example
{
"payload": {
"title": "Additional Inputs",
"required": [
"shipment",
"items"
],
"properties": {
"shipment": {
"title": "Shipment Inputs",
"required": [
"NON_DELIVERABLE_INSTRUCTIONS",
"SENDER_ADDRESS_TRANSLATED"
],
"properties": {
"NON_DELIVERABLE_INSTRUCTIONS": {
"title": "Non-Deliverable Instructions",
"default": "ABANDON",
"enum": [
"ABANDON",
"RETURN_TO_SELLER"
],
"type": "string"
},
"SENDER_ADDRESS_TRANSLATED": {
"title": "Ship From Address (Chinese)",
"required": [
"city",
"countryCode",
"postalCode",
"name",
"line1"
],
"properties": {
"stateOrRegion": {
"title": "State",
"type": "string"
},
"phoneNumber": {
"title": "Phone Number",
"type": "string"
},
"city": {
"title": "City",
"type": "string"
},
"countryCode": {
"title": "Country Code",
"type": "string"
},
"postalCode": {
"title": "Postal Code",
"type": "string"
},
"name": {
"title": "Customer Name",
"type": "string"
},
"line3": {
"title": "Line 3",
"type": "string"
},
"line2": {
"title": "Line 2",
"type": "string"
},
"line1": {
"title": "Line 1",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"items": {
"title": "Item Inputs",
"required": [
"B004UHQD1O"
],
"properties": {
"B004UHQD1O": {
"title": "B004UHQD1O",
"required": [
"ITEM_WEIGHT",
"ITEM_DESCRIPTION_TRANSLATED",
"COUNTRY_OF_ORIGIN",
"ITEM_VALUE",
"ITEM_DESCRIPTION"
],
"properties": {
"ITEM_WEIGHT": {
"title": "Item weight",
"required": [
"unit",
"value"
],
"properties": {
"unit": {
"title": "Unit",
"enum": [
"GRAM",
"KILOGRAM",
"POUND",
"OUNCE"
],
"type": "string"
},
"value": {
"title": "Value",
"type": "number"
}
},
"type": "object"
},
"ITEM_DESCRIPTION_TRANSLATED": {
"title": "Item Description (Chinese)",
"pattern": "^([a-zA-Z0-9\\W])",
"type": "string"
},
"COUNTRY_OF_ORIGIN": {
"title": "Country of Origin",
"pattern": "^[a-zA-Z]{2}$",
"type": "string"
},
"ITEM_VALUE": {
"title": "Item Value (USD)",
"required": [
"unit",
"value"
],
"properties": {
"unit": {
"title": "Unit",
"enum": [
"USD",
"GBP"
],
"type": "string"
},
"value": {
"title": "Value",
"type": "number"
}
},
"type": "object"
},
"ITEM_DESCRIPTION": {
"title": "Item Description",
"pattern": "^[a-zA-Z0-9-._& ]{3,25}$",
"type": "string"
},
"HS_CODE": {
"title": "HS Code",
"pattern": "^[0-9 -]{1,10}?$",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}
}
Step 3. Purchase a shipment
After getting rates and discovering any required additional inputs, you can purchase an available shipping service. If additional inputs are required for the service you want to purchase, you must provide them when you call the purchaseShipment operation as part of this step.
You must complete the purchase within 10 minutes of the creation of the rate 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.
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.
To purchase and create a shipment:
Call the purchaseShipment operation, passing the following request parameters:
Request parameters
Request body
Name | Description | Required |
---|---|---|
requestToken | A unique token generated to identify a getRates operation.
Type: RequestToken |
Yes |
rateId | An identifier for the rate (shipping offering) selected from among those returned in the response to the getRates operation. This rate expires 10 minutes after 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". Type: RateId |
Yes |
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. | Yes |
requestedValueAddedServices | The value-added services to be added to a shipping service purchase. | No |
additionalInputs | 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. Type: object |
No |
Request header parameters
Name | Description | Required |
---|---|---|
x-amzn-IdempotencyKey | A unique value which the server uses to recognize subsequent retries of the same request.
Type: string |
No |
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Request example without additional inputs
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments
{
"requestToken": "amzn1.dd2b0cec-b215-4504-b94d-d6469b0c4a63",
"rateId": "e1b7cf2d1516d8c5343a087e10a5a2261ff36b83bdb5a91c6ce51b19586ed9861507200580943",
"requestedDocumentSpecification": {
"format": "PNG",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"dpi": 300,
"pageLayout": "DEFAULT",
"needFileJoining": false,
"requestedDocumentTypes": [
"LABEL"
]
}
}
Response
A successful response includes the following:
Name | Description | Schema |
---|---|---|
payload | The payload for the purchaseShipment operation. | PurchaseShipmentResult |
Response example without additional inputs
{
"payload": {
"shipmentId": "amzn1.dd2b0cec-b215-4504-b94d-d6469b0c4a63",
"packageDocumentDetails": [
{
"packageClientReferenceId": "abcdef",
"packageDocuments": [
{
"type": "LABEL",
"contents": "iVBORw0KGgoAAAANSUhEUgAABLAAAAcIAgAAAABDi383AAAACXBIWXMAAC4jAAAuIwF4pT92AABFlUlEQV",
"format": "PNG"
}
],
"trackingId": "90171138606915760111801497834333303801954"
}
],
"promise": {
"pickupWindow": {
"startTime": "2017-10-05T10:35:12.373Z",
"endTime": "2017-10-05T10:35:12.373Z"
},
"deliveryWindow": {
"startTime": "2017-10-05T10:35:12.373Z",
"endTime": "2017-10-05T10:35:12.373Z"
}
}
}
}
Request example with additional inputs
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments
{
"requestToken": "amzn1.rq.5cbe8664-285e-4bd5-8a70-db2ed9ba017e.101",
"rateId": "9559ad41-c9da-43b8-aed9-5684e6a76be8",
"requestedDocumentSpecification": {
"format": "PDF",
"size": {
"width": 15,
"length": 10,
"unit": "CENTIMETER"
},
"pageLayout": "LEFT",
"needFileJoining": true,
"requestedDocumentTypes": [
"LABEL"]
},
"requestedValueAddedServices": [
{
"id": "DELIVERY_CONFIRMATION"
},
{
"id": "SHIPPER_DROPOFF_CHARGE"
}
],
"additionalInputs": {
"shipment": {
"SENDER_ADDRESS_TRANSLATED": {
"city": "",
"countryCode": "CN",
"postalCode": "510810",
"name": "",
"line1": "",
"line2": "",
"line3": " ",
"stateOrRegion": "",
"phoneNumber": "555-555-5555"
},
"NON_DELIVERABLE_INSTRUCTIONS": "RETURN_TO_SELLER"
},
"items": {
"B004UHQD1O": {
"ITEM_WEIGHT": {
"unit": "GRAM",
"value": 250
},
"ITEM_VALUE": {
"unit": "USD",
"value": 1
},
"COUNTRY_OF_ORIGIN": "CN",
"ITEM_DESCRIPTION_TRANSLATED": "",
"ITEM_DESCRIPTION": "penbox"
}
}
}
}
Response example with additional inputs
{
"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 [Currently, this API is paused until further development work is complete]
This tutorial shows how to purchase a shipment directly. You will want to use this operation if you are a vendor's own carrier vendor shipping a Direct Fulfillment order. Amazon will select the best fit ship option for Direct Fulfillment shipment. This means Amazon determines the shipping option most likely to meet the promised delivery date. 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:
- Enrollment in the Direct Fulfillment program, where you will need a Vendor Central account if you are an Amazon vendor.
-
Authorization from the selling-partner 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
Purchasing a shipment directly purchases the best fit ship option without the need to review rates. If you are fulfilling a Direct Fulfillment order, please provide the directFulfillmentItemIdentifiers for each Item in a package.
To purchase a shipment directly:
Call the directPurchaseShipment operation to get a label directly without a rates request, passing the following parameters:
Request parameters
Request body
Name | Description | Required |
---|---|---|
shipTo | The address where the shipment will be delivered. For vendor orders, shipTo information is pulled directly from the Amazon order.
Type: Address |
Conditional |
shipFrom | The address where the package will be picked up.
Type: Address |
Conditional |
returnTo | The address where the package will be returned if it cannot be delivered.
Type: Address |
No |
packages | A list of packages to be shipped including the package details.
Type: PackageList |
Conditional |
channelDetails | Shipment source channel related information.
Type: ChannelDetails |
Yes |
labelSpecifications | 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. | No |
Request header parameters
Name | Description | Required |
---|---|---|
x-amzn-IdempotencyKey | A unique value which the server uses to recognize subsequent retries of the same request.
Type: string |
No |
locale | 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.
Type: string |
No |
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Request example
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/directPurchase
x-amzn-IdempotencyKey: 6f01ef39-43eb-4d0f-94fa-e3f25f0bfba2
locale: en-US
x-amzn-shipping-business-id: AmazonShipping_US
{
"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"
},
"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:
Name | Description | Schema |
---|---|---|
payload | The payload for the directPurchaseShipment operation. | DirectPurchaseResult |
Response example
{
"payload": {
"shipmentId": "445454-3232-3232",
"packageDocumentDetailList": [
{
"packageClientReferenceId": "ASUSDI-45343854",
"trackingId": "T1234567",
"packageDocuments": [
{
"type": "LABEL",
"format": "ZPL",
"contents": "iVBORw0KGgoAAAANALiAXEAmIBsYBYALGAWEAsIBYQC4gFxAKIBcQCYgGxgFhALIBYQCwgFhALiAXEAmIByv4PwWms3AV97VoAAAAASUVORK5CYII="
}
]
}
]
}
}
Tutorial: Retrieve previously generated shipment documents
This tutorial shows how to return previously generated shipping documents for a single package. For example, you might retrieve a previously generated label for reprinting.
NOTE: The getShipmentDocuments
operation returns shipping documents in the document format originally requested. For instance, if you request a label in PNG format when you purchase a shipment, a subsequent call to getShipmentDocuments
returns the original PNG format label. If you need a different document type, you must cancel the shipment and generate a new shipment with the desired document type.
NOTE: This operation is not unavailable for Direct Fulfillment shipments.
Prerequisites
To complete this tutorial, you will need:
-
Enrollment in an eligible program.
-
A selling-partner account if you are an Amazon seller or are working with an Amazon seller to create and manage shipments.
-
Authorization from the selling-partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.
Step 1. Retrieve previously generated shipping documents
To return previously generated shipment documents:
Call the getShipmentDocuments operation for a shipment, passing the following parameters:
Request parameters
Request path parameter
Name | Description | Required |
---|---|---|
shipmentID | The shipment identifier originally returned by the purchaseShipment operation.
Type: string |
Yes |
Request query parameters
Name | Description | Required |
---|---|---|
packageClientReferenceID | The package client reference identifier originally provided in the request body parameter for the getRates operation.
Type: string |
Yes |
format | The file format of the document. Must be one of the supported formats returned by the getRates operation.
Type: string |
No |
dpi | The resolution of the document (for example, 300 means 300 dots per inch).
Type: number |
No |
Request header parameter
Name | Description | Required |
---|---|---|
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Request example
GET https://sellingpartnerapi-eu.amazon.com/shipping/sandbox/v2/shipments/amzn1.dd2b0cec-b215-4504-b94d-d6469b0c4a63/documents?packageClientReferenceId=abcd&format=PNG&dpi=300
Response
A successful response includes the following:
Name | Description | Required |
---|---|---|
shipmentId | Returns the unique shipment identifier for a given shipment.
Type: string |
Yes |
packageDocumentDetail | Container for package document details.
Type: PackageDocumentDetail |
Yes |
Response example
{
"payload": {
"shipmentId": "amzn1.dd2b0cec-b215-4504-b94d-d6469b0c4a63",
"packageDocumentDetail": {
"packageClientReferenceId": "ASUSDI-45343854",
"packageDocuments": [
{
"type": "LABEL",
"contents": "iVBORw0KGgoAAAANSUhEUgAABLAAAAcIAgAAAABDi383AAAACXBIWXMAAC4jAA4/JrkGaSNZARsAAAAASUVORK5CYII=",
"format": "PNG"
}
],
"trackingId": "90171138606915760111801497834333303801954"
}
}
}
Tutorial: Track a shipment
This tutorial shows how to track a previously created shipment. The getTracking operation provides tracking information for packages shipped with Amazon, including the most recent status and package status history.
NOTE: This operation will only return a response for packages shipped with Amazon, and is unavailable for Direct Fulfillment shipments. To track Amazon orders shipped with another carrier, please call the respective carrier's tracking API directly. For packages shipped with Amazon, you can retrieve tracking details for up to 45 days after the shipment creation date. After this period, only the last tracking status is returned.
Prerequisites
To complete this tutorial, you will need:
-
Enrollment in an eligible program.
-
A selling-partner account if you are an Amazon seller or are working with an Amazon seller to create and manage shipments.
-
Authorization from the selling-partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.
Step 1. Track a shipment
To get the tracking status and package status history:
Call the getTracking operation for a shipment, passing the following parameters:
Request Parameters
Query Parameters
Name | Description | Required |
---|---|---|
carrierID |
A carrier identifier originally returned by the getRates operation for the selected rate.
Type: string |
Yes |
trackingID |
A carrier-generated tracking identifier originally returned by the purchaseShipment operation.
Type: string |
Yes |
Request header parameters
Name | Description | Required |
---|---|---|
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Request example
GET https://sellingpartnerapi-eu.amazon.com/shipping/v2/tracking?carrierId=AMZN_UK&trackingId=1582657452914
Response
A successful response includes the following:
Name | Description | Schema |
---|---|---|
payload | The payload for the getTracking operation. | GetTrackingResult |
Response example
{
"payload": {
"eventHistory": [
{
"eventTime": "2019-03-12T14:04:50Z",
"eventCode": "ReadyForReceive",
"location": null
},
{
"eventTime": "2019-04-12T05:23:29Z",
"eventCode": "PickupDone",
"location": {
"stateOrRegion": "Leicestershire",
"countryCode": "GB",
"city": "Bardon",
"postalCode": "LE67 1LD"
}
},
{
"eventTime": "2019-04-13T16:23:29Z",
"eventCode": "DeliveryAttempted",
"location": {
"stateOrRegion": "Leicestershire",
"countryCode": "GB",
"city": "Bardon",
"postalCode": "LE67 1LD"
}
},
{
"eventTime": "2019-04-14T16:23:29Z",
"eventCode": "Delivered",
"location": {
"stateOrRegion": "Leicestershire",
"countryCode": "GB",
"city": "Bardon",
"postalCode": "LE67 1LD"
}
}
],
"summary": {
"status": "Delivered"
},
"trackingId": "1582657452914",
"promisedDeliveryDate": "2019-03-13T20:00:00Z"
}
}
Tutorial: Cancel a shipment
This tutorial shows how to cancel a previously created shipment. The cancelShipment operation cancels a shipment that has not been picked up for delivery. If the shipment has already been picked up, you cannot cancel it.
NOTE: Carrier cancellation windows vary. Please see Seller Central help for carrier-specific cancellation/refund windows.
NOTE: The cancelShipment operation is not available for Direct Fulfillment shipments.
Prerequisites
To complete this tutorial, you will need:
-
Enrollment in an eligible program.
-
A selling-partner account if you are an Amazon seller or are working with an Amazon seller to create and manage shipments.
-
Authorization from the selling-partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.
Step 1. Cancel a shipment
To cancel a previously created shipment:
Call the cancelShipment operation for a shipment, passing the following parameter.
Name | Description | Required |
---|---|---|
shipmentID |
The shipment identifier originally returned by the purchaseShipment operation.
Type: string |
Yes |
Request header parameter
Name | Description | Required |
---|---|---|
x-amzn-shipping-business-id |
Amazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id) |
Yes |
Request example
PUT https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/amzn1.sid.87906797587784.100/cancel
Response
A successful response includes the following:
An empty 200 payload object indicates successful cancellation.
Response example
{
"payload": {}
}
Updated 9 months ago