Tutorial: Use the SmartPurchase API to Generate Amazon Shipping Labels

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 (`X-amzn-shipping-business-id`)	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.