Tutorial: Use the SmartPurchase API to Generate Amazon Shipping Labels
How to use the SmartPurchase API.
API Version: v2
This tutorial provides a comprehensive guide on how to use the SmartPurchase API. The API is designed to expedite the process of generating Amazon Shipping labels. By leveraging the capabilities of the SmartPurchase API, users can streamline their shipping workflows, enhance label creation speed, and improve overall operational efficiency.
Please note that Amazon Shipping labels generated for Amazon marketplace orders (On-Amazon) using the SmartPurchase API do not include Amazon Buy Shipping protections. Therefore, it is important to consider this limitation when utilizing the API for your shipping requirements. If sellers wish to leverage Amazon Buy Shipping protection, it is recommended to use the Tutorial: Purchase a Shipment From a Rate instead.
Prerequisites
To complete this tutorial you will need:
- Enrollment in an eligible program
- The Direct to Consumer Shipping (Restricted) role or the Amazon Logistics role. The Direct to Consumer Shipping (Restricted) role will support label creation for Amazon marketplace orders and orders from other sources, such as the seller's website. The Amazon Logistics role will support label creation for non-Amazon order sources only.
- 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 Authorizing Selling Partner API applications for more information.
Step 1. Generate an Amazon Shipping label
Call the oneClickShipment
operation.
Request
Name | Description | Schema |
---|---|---|
shipTo | The ship to address. shipTo is optional for Amazon Marketplace orders and mandatory for non-Amazon marketplace orders. | Address |
shipFrom required | The ship from address. | Address |
returnTo optional | The return to address. | Address |
shipDate optional | The ship date and time (the requested pickup). This defaults to the current date and time. | string (date-time) |
packages required | A list of packages to be shipped through a shipping service offering. | PackageList |
valueAddedServicesDetails optional | The value-added services to be added to a shipping service purchase. | OneClickShipmentValueAddedServiceDetails |
taxDetails optional | A list of tax detail information. | TaxDetailList |
channelDetails required | Shipment source channel related information. | ChannelDetails |
labelSpecifications required | The document specifications requested. Calls to the oneClickShipment operation fail if the document specifications are not ZPL, PDF, or PNG. You can find the available label specifications on the Amazon Shipping FAQ | RequestedDocumentSpecification |
serviceSelection required | Service Selection Criteria. | ServiceSelection |
shipperInstruction optional | Optional field for shipper instruction. | ShipperInstruction |
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 ( |
Yes |
x-amzn-access-token |
Amazon shipping request token | Yes |
Response
A successful response includes the following:
Name | Description | Schema |
---|---|---|
shipmentId | The unique shipment identifier provided by a shipping service. | ShipmentId |
packageDocumentDetails | A list of post-purchase details about a package that will be shipped using a shipping service. | PackageDocumentDetailList |
promise | The time windows promised for pickup and delivery events. | Promise |
carrier | Carrier Related Info | Carrier |
service | Service Related Info | Service |
totalCharge | The monetary value in the currency indicated, in ISO 4217 standard format. | Currency |
Sample API Request
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/oneClickShipment
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
Off-Amazon request for UK (AmazonShipping_UK)
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/oneClickShipment
x-amzn-shipping-business-id: AmazonShipping_UK
x-amz-access-token: Atza|IwEBIGorlXXX
{
"shipTo": {
"name": "John Doe",
"addressLine1": "1 Principal Place",
"city": "London",
"countryCode": "GB",
"postalCode": "EC2A 2FA",
"email": "[email protected]",
"phoneNumber": "+44 444 444 4444"
},
"shipFrom": {
"name": "New Shipper WH",
"addressLine1": " Plot 510, GLP, Magna Park",
"stateOrRegion": "string",
"city": "Milton Keynes",
"countryCode": "GB",
"postalCode": "MK17 8EW",
"email": "[email protected]",
"phoneNumber": "+44 444 444 4444"
},
"packages": [
{
"dimensions": {
"length": 5,
"width": 5,
"height": 5,
"unit": "INCH"
},
"weight": {
"unit": "GRAM",
"value": 1200
},
"insuredValue": {
"value": 10,
"unit": "GBP"
},
"isHazmat": false,
"sellerDisplayName": "New Shoes and Company",
"packageClientReferenceId": "Order-12345",
"items": [
{
"itemValue": {
"value": 10,
"unit": "GBP"
},
"description": "Clothes",
"itemIdentifier": "Clothes",
"quantity": 1,
"weight": {
"unit": "GRAM",
"value": 1000
},
"isHazmat": false
}
]
}
],
"channelDetails": {
"channelType": "EXTERNAL"
},
"serviceSelection": {
"serviceId": [
"SWA-UK-PREM"
]
},
"labelSpecifications": {
"format": "PDF",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"dpi": 300,
"pageLayout": "DEFAULT",
"needFileJoining": false,
"requestedDocumentTypes": [
"LABEL"
]
}
}
Note: The above examples are for the UK marketplace. Inputs such as serviceId
and currency
would differ based on marketplace. You can find other service IDs in the Amazon Shipping FAQ.
On-Amazon request for US (AmazonShipping_US)
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/oneClickShipment
x-amzn-shipping-business-id: AmazonShipping_US
x-amz-access-token: Atza|IwEBIGorlXXX
{
"shipTo": {
"name": "End Customer Address",
"addressLine1": "4650 CREEK RD",
"city": "CINCINNATI",
"stateOrRegion": "OH",
"countryCode": "US",
"postalCode": "45242-2806",
"email": "[email protected]",
"phoneNumber": "999999999"
},
"shipFrom": {
"name": "Seller Warehouse",
"addressLine1": "4350 Temple City Blvd",
"stateOrRegion": "CA",
"city": "El Monte",
"postalCode": "91731",
"countryCode": "US"
},
"packages": [
{
"insuredValue": {
"unit": "USD",
"value": 0
},
"weight": {
"unit": "POUND",
"value": 5
},
"items": [
{
"quantity": 1,
"itemValue": {
"unit": "USD",
"value": 1.02
},
"description": "SWA SmartP ON Amazon",
"weight": {
"unit": "POUND",
"value": 5
},
"itemIdentifier": "83466579378321",
"isHazmat": false
}
],
"isHazmat": false,
"packageClientReferenceId": "SWA_SmartP_Test1",
"dimensions": {
"unit": "INCH",
"length": 3,
"width": 3.14,
"height": 3.14
}
}
],
"channelDetails": {
"channelType": "AMAZON",
"amazonOrderDetails": {
"orderId": "113-4698573-5624269"
}
},
"serviceSelection": {
"serviceId": [
"std-us-swa-mfn"
]
},
"labelSpecifications": {
"format": "PDF",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"dpi": 300,
"pageLayout": "DEFAULT",
"needFileJoining": false,
"requestedDocumentTypes": [
"LABEL"
]
}
}
Off-Amazon request for IN (AmazonShipping_IN)
POST https://sellingpartnerapi-eu.amazon.com/shipping/v2/oneClickShipment
x-amzn-shipping-business-id: AmazonShipping_IN
x-amz-access-token: Atza|IwEBIGorlXXX
{
"shipTo": {
"name": "End Customer Name",
"addressLine1": "Hyderabad King koti",
"addressLine2": "30, Aryan Mahal, 6th Floor",
"addressLine3": "string",
"companyName": "new Shoes",
"stateOrRegion": "telangana",
"city": "Hyderabad",
"countryCode": "IN",
"postalCode": "500008",
"email": "[email protected]",
"phoneNumber": "9999999999"
},
"shipFrom": {
"name": "Seller WH Address",
"addressLine1": "Ship to Line 1",
"addressLine2": "Ship to Line 2",
"addressLine3": "Ship to Line 3",
"companyName": "new place",
"stateOrRegion": "Telangana",
"city": "Hyderabad",
"countryCode": "IN",
"postalCode": "122001",
"email": "[email protected]",
"phoneNumber": "1111111111"
},
"returnTo": {
"name": "Seller WH Address",
"addressLine1": "Ship to Line 1",
"addressLine2": "Ship to Line 2",
"addressLine3": "Ship to Line 3",
"companyName": "new place",
"stateOrRegion": "Telangana",
"city": "Hyderabad",
"countryCode": "IN",
"postalCode": "122001",
"email": "[email protected]",
"phoneNumber": "1111111111"
},
"packages": [
{
"dimensions": {
"length": 13,
"width": 9,
"height": 17,
"unit": "CENTIMETER"
},
"weight": {
"unit": "GRAM",
"value": 400
},
"insuredValue": {
"value": 1,
"unit": "INR"
},
"isHazmat": false,
"sellerDisplayName": "SD Test",
"packageClientReferenceId": "12345",
"items": [
{
"itemValue": {
"value": 2,
"unit": "INR"
},
"description": "description of item1",
"itemIdentifier": "item-11111",
"quantity": 1,
"weight": {
"unit": "GRAM",
"value": 400
},
"isHazmat": false,
"productType": "health care",
"invoiceDetails": {
"invoiceNumber": "1234567",
"invoiceDate": "2022-05-31T18:28:43Z"
}
}
]
}
],
"valueAddedServiceDetails": [
{
"id": "CollectOnDelivery",
"amount": {
"unit": "INR",
"value": 50
}
}
],
"taxDetails": [
{
"taxType": "GST",
"taxRegistrationNumber": "anbp1234"
}
],
"channelDetails": {
"channelType": "EXTERNAL"
},
"serviceSelection": {
"serviceId": [
"SWA-IN-OA"
]
},
"labelSpecifications": {
"format": "PDF",
"size": {
"width": 4,
"length": 6,
"unit": "INCH"
},
"dpi": 203,
"pageLayout": "DEFAULT",
"needFileJoining": false,
"requestedDocumentTypes": [
"LABEL"
]
}
}
On-Amazon response for UK
{
"shipmentId": "amzn1.sid.97457791053026.100",
"packageDocumentDetails": [
{
"packageClientReferenceId": "Order-12345",
"packageDocuments": [
{
"contents": "<Shipping Label Base64 Encoded>",
"type": "LABEL",
"format": "PDF"
}
],
"trackingId": "A11889075833"
}
],
"promise": {
"pickupWindow": {
"start": "2023-05-31T16:00:00.000Z",
"end": "2023-05-31T17:00:00.000Z"
},
"deliveryWindow": {
"start": "2023-06-01T20:00:00.000Z",
"end": "2023-06-01T21:00:00.000Z"
}
},
"carrier": {
"id": "AMZN_UK",
"name": "Amazon Shipping"
},
"service": {
"id": "prime-premium-uk-mfn",
"name": "Amazon Shipping One-Day Tracked"
},
"totalCharge": {
"unit": "GBP",
"value": 2.10
}
}
Note 1: The above example is for the UK marketplace. Outputs such as serviceId
and carrierId
differ based on marketplace. You can find other service IDs in the Amazon Shipping FAQ.
Updated 2 months ago