Tutorial: Purchase a Shipment From a Rate

How to get rates for a shipment, get any additional inputs when required, and purchase a shipment.

API Version: v2

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. Refer to Authorizing Selling Partner API applications for more information.

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, the Amazon order number must be provided in the channel details.

Amazon Order

"channelDetails": {
  "channelType": "AMAZON",
  "amazonOrderDetails": {
    "orderId": "912-1061508-5843035"
  }
}

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.

Request

To get the rates for a shipment, call the getRates operation, passing the following parameters:

NameDescriptionRequired
shipToThe address where the shipment will be delivered. For Amazon orders, shipTo information is pulled directly from the Amazon order.
Type: Address
Conditional
shipFromThe address where the package will be picked up.
Type: Address
Yes
returnToThe address where the package will be returned if it cannot be delivered.
Type: Address
No
shipDateThe ship date and time (the requested pickup). This defaults to the current date and time.
Type: string (date-time)
No
packagesA list of packages to be shipped and package details.
Type: PackageList
Yes
valueAddedServicesA collection of supported value-added services.
Type: ValueAddedServiceDetails
No
taxDetailsA list of tax detail information.
Type: TaxDetailList
No
channelDetailsShipment source channel related information.
Type: ChannelDetails
Yes

Request header parameters

NameDescriptionRequired
x-amzn-shipping-business-idAmazon shipping business to assume for this request. The default is AmazonShipping_UK.
Type: enum (X-amzn-shipping-business-id)
Yes
x-amzn-access-tokenAmazon shipping request tokenYes

Response

A successful response includes the following:

NameDescriptionSchema
payloadThe payload for the getRates operation.GetRatesResult

Sample API Request

POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: [x-amzn-shipping-business-id](https://developer-docs.amazon.com/amazon-shipping/docs/frequently-asked-questions#which-x-amzn-shipping-business-id-to-use-as-request-header-while-calling-shipping-v2-api)
x-amz-access-token: Atza|IwEBIGorlXXX

API Request and Response examples for UK (AmazonShipping_UK)

POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: AmazonShipping_UK
x-amz-access-token: Atza|IwEBIGorlXXX

Off-Amazon request

{
  "shipTo": {
    "name": "Pavan",
    "addressLine1": "12, Meersbrook Park Road",
    "addressLine2": "Meersbrook",
    "postalCode": "OX15 6NA",
    "city": "SHEFFIELD",
    "countryCode": "GB",
    "email": "[email protected]",
    "phoneNumber": "9999999999"
  },
  "shipFrom": {
    "name": "A1",
    "addressLine1": "Plane Tree Crescent",
    "postalCode": "S8 9FP",
    "city": "Feltham",
    "countryCode": "GB",
    "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
          }
        },
        {
          "quantity": 1,
          "weight": {
            "unit": "KILOGRAM",
            "value": 1.14159
          }
        }
      ],
      "insuredValue": {
        "unit": "GBP",
        "value": 29.98
      },
      "packageClientReferenceId": "abcd"
    }
  ],
  "channelDetails": {
    "channelType": "EXTERNAL"
  }
}

Off-Amazon response

{
  "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

{
  "shipTo": {
    "name": "Pavan",
    "addressLine1": "12, Meersbrook Park Road",
    "addressLine2": "Meersbrook",
    "postalCode": "OX15 6NA",
    "city": "SHEFFIELD",
    "countryCode": "GB",
    "email": "[email protected]",
    "phoneNumber": "9999999999"
  },
  "shipFrom": {
    "name": "A1",
    "addressLine1": "Plane Tree Crescent",
    "postalCode": "S8 9FP",
    "city": "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

{
  "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"
  }
}

API Request and Response examples with tax details for India (AmazonShipping_IN)

POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments/rates
x-amzn-shipping-business-id: AmazonShipping_IN
x-amz-access-token: Atza|IwEBIGorlXXX

Off-Amazon request

{
  "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

{
  "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 places, so we recommend that you do not cache or 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 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 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)

No
x-amzn-access-token Amazon shipping request token Yes

Response

A successful response includes the following:

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

API 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
x-amz-access-token: Atza|IwEBIGorlXXX

API 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 of 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, create a separate shipment for each package.

To purchase and create a shipment, call the purchaseShipment operation, passing the following request parameters:

Request

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
x-amzn-access-token Amazon shipping request token Yes

Response

A successful response includes the following:

NameDescriptionSchema
payloadThe payload for the purchaseShipment operation.PurchaseShipmentResult

Sample API Request

POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/shipments
x-amzn-shipping-business-id: [x-amzn-shipping-business-id](https://developer-docs.amazon.com/amazon-shipping/docs/frequently-asked-questions#which-x-amzn-shipping-business-id-to-use-as-request-header-while-calling-shipping-v2-api)
x-amz-access-token: Atza|IwEBIGorlXXX

API Request and Response examples

Request without additional inputs

{
  "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 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 with additional inputs

{
  "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 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"
      }
    }
  }
}