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:

Create a shipment workflow

Here is the recommended workflow for creating a vendor own carrier Direct Fulfillment shipment:

Direct fulfillment shipment workflow

Here is the recommended workflow for managing a shipment. These operations are not available for Direct Fulfillment shipments.

Managing a shipment workflow

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 3. Purchase 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. Type: RequestedDocumentSpecification	Yes
requestedValueAddedServices	The value-added services to be added to a shipping service purchase. Type: RequestedValueAddedServiceList	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. Type: RequestedDocumentSpecification	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": {}
}