Amazon Buy Shipping: Rates, Labels, Tracking and Manifests

The amazon carrier uses the Amazon Shipping API v2, the Selling Partner API behind two Amazon programs:

• Amazon Buy Shipping: labels for orders placed on Amazon, from Amazon Shipping and every other carrier enabled in the seller's Buy Shipping settings (UPS, USPS, FedEx, DHL and others depending on the marketplace). Labels bought this way carry Amazon's Buy Shipping protections: on-time delivery guarantees, claims protection and valid tracking.
• Amazon Shipping: Amazon's own carrier for orders from any channel.

The legacy amazon-mws carrier (Merchant Fulfillment via MWS) is unrelated.

Credentials#

Create an SP-API application in Seller Central (Apps & Services, Develop Apps) with the Amazon Shipping role, then self-authorize it to get a refresh token. Every request needs the Login with Amazon (LWA) credentials of that app:

RocketShipIt exchanges the refresh token for a one-hour access token on every request. To skip that round trip, run the authenticate action and pass the returned access token as key until it expires. The same values can come from the environment as RS_AMAZON_CLIENT_ID, RS_AMAZON_CLIENT_SECRET, RS_AMAZON_REFRESH_TOKEN and RS_AMAZON_APPLICATION_ID. The secrets and the access token are redacted from meta.debug_information.

application_id defaults to AmazonShipping_US. It also picks the regional host (North America, Europe or Far East) and the default currency for insured and item values; set currency to override the currency.

Test mode#

Setting "test": true sends the request to Amazon's sandbox host, which answers with canned responses and never buys a label. The sandbox does not validate your input beyond the schema, and its service IDs differ from production.

Supported actions#

Buy Shipping flow#

Buy Shipping is a two step purchase. First rate the shipment with the Amazon order ID in order.id. Amazon already knows the buyer's address, so the to_* fields can be left out; when given they must match the order.

{
  "carrier": "amazon",
  "action": "getallrates",
  "params": {
    "client_id": "amzn1.application-oa2-client.abc123",
    "client_secret": "your-client-secret",
    "refresh_token": "Atzr|your-refresh-token",
    "application_id": "AmazonShipping_US",
    "order": { "id": "111-7676169-9674624" },
    "packages": [
      {
        "weight": 3.4,
        "length": 20,
        "width": 12,
        "height": 12,
        "insured_value": 89.98,
        "items": [
          { "id": "28367575711066", "quantity": 1, "weight": 1.2, "value": 49.99, "description": "Blue widget" },
          { "id": "28367575711067", "quantity": 1, "weight": 2.2, "value": 39.99, "description": "Red widget" }
        ]
      }
    ],
    "shipper": "Your Company",
    "ship_name": "Warehouse",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "ship_country": "US",
    "ship_phone": "1231231234",
    "weight_unit": "LB",
    "length_unit": "IN"
  }
}

Every rate in the response carries a rate_id, the carrier behind it and the services that can be added to it. The response also carries one request_token for the whole rate set:

{
  "data": {
    "request_token": "amzn1.rq.00607789216708.101",
    "rates": [
      {
        "rate_id": "e1b7cf2d1516d8c5343a087e10a5a2261ff36b83bdb5a91c6ce51b19586ed98615072005809431",
        "carrier_code": "AMZN_US",
        "carrier_name": "Amazon Shipping",
        "service_code": "std-us-swa-mfn",
        "desc": "Amazon Shipping Ground",
        "rate": 7.42,
        "currency": "USD",
        "est_delivery_time": "2026-09-07T23:59:59Z",
        "billing_weight": 5,
        "billing_weight_units": "POUND",
        "payment_type": "PAY_THROUGH_AMAZON",
        "rate_detail": [
          { "type": "BASE_RATE", "amount": 6.92, "currency": "USD" },
          { "type": "FUEL_SURCHARGE", "amount": 0.5, "currency": "USD" }
        ],
        "value_added_services": [
          { "id": "SIGNATURE_CONFIRMATION", "name": "Signature confirmation", "group": "DELIVERY_CONFIRMATION", "amount": 2.5, "currency": "USD" }
        ]
      }
    ]
  }
}

Then buy the chosen rate within 10 minutes. The purchase needs only the two tokens, the label format and any extras:

{
  "carrier": "amazon",
  "action": "submitshipment",
  "params": {
    "client_id": "amzn1.application-oa2-client.abc123",
    "client_secret": "your-client-secret",
    "refresh_token": "Atzr|your-refresh-token",
    "application_id": "AmazonShipping_US",
    "request_token": "amzn1.rq.00607789216708.101",
    "rate_id": "e1b7cf2d1516d8c5343a087e10a5a2261ff36b83bdb5a91c6ce51b19586ed98615072005809431",
    "unique_id": "order-111-7676169-9674624-label-1",
    "image_type": "rs_zpl",
    "addons": ["SIGNATURE_CONFIRMATION"]
  }
}

A rate with requires_additional_inputs: true needs carrier-specific inputs (Amazon's getAdditionalInputs schema) that RocketShipIt does not collect yet. Pick another rate or contact us with the carrier you need.

The response is the usual RocketShipIt shipment: shipment_id (needed to void or re-download the label), one package per packages entry with its tracking number, label and documents. Each document is tagged with the package_client_reference_id Amazon assigned, which is the package's reference_value or pkg-1, pkg-2, ... in order.

One-step labels#

Without request_token, submitshipment calls oneClickShipment, which rates and buys in one call. Put the Amazon service IDs to consider in service (comma separated for several) and Amazon buys the cheapest eligible one. Add order.id to ship an Amazon order this way. One-step labels do not carry the Buy Shipping protections; use the two step flow for orders that need them.

Production Amazon Shipping service IDs include std-us-swa-mfn (US), std-uk-mfn, prime-premium-uk-mfn, econ-uk-mfn, SWA-UK-PREM, SWA-UK-2D (UK) and the FR, IT, ES and IN equivalents. Rate first to see the IDs available to your account.

Packages and items#

Amazon needs the weight, dimensions, an insured value and at least one item for every package. RocketShipIt fills in what you leave out: insured_value defaults to 0 and a package without items is sent as one item of the package's weight and description.

Each entry of items describes one line of the package's contents:

For a single-package shipment with no items, the order.items list (id and quantity, the format the amazon-mws carrier used) is sent as the package's items.

Other shipment options#

Tracking#

track needs the tracking number and the carrier that issued it. Send the rate's carrier_code (AMZN_US, UPS, USPS, ...) as carrier_code; it defaults to Amazon Shipping in the business ID's country (AMZN_US, AMZN_UK, ATS for India).

{
  "carrier": "amazon",
  "action": "track",
  "params": {
    "client_id": "amzn1.application-oa2-client.abc123",
    "client_secret": "your-client-secret",
    "refresh_token": "Atzr|your-refresh-token",
    "application_id": "AmazonShipping_US",
    "tracking_number": "TBA123456789000",
    "carrier_code": "AMZN_US"
  }
}

The activity lists Amazon's event codes (ReadyForReceive, PickupDone, ArrivedAtCarrierFacility, Departed, OutForDelivery, Delivered, DeliveryAttempted, AvailableForPickup, Undeliverable, Rejected, Lost, PickupCancelled, ReturnInitiated) with a plain-English description. delivery_detail holds the promised delivery date until the package is delivered, then the delivery time, the recipient and the proof of delivery photo or signature URL. Amazon's detail codes (DeliveredToPorch, Signed, ...) are listed under the package's messages.

Voiding a label#

voidshipment cancels the shipment named by shipment_id. Amazon refunds labels cancelled before the carrier scans the package.

Re-downloading a label#

labelrecovery fetches the documents of one package of a purchased shipment again: shipment_id plus package_id, the package's package_client_reference_id (pkg-1 unless the package had a reference_value). Set image_type to convert the label to another format.

Manifests (collection forms)#

createmanifest generates the collection form the carrier's driver scans at pickup, covering every unmanifested shipment of carrier_code (default: Amazon Shipping) from the ship_* address. The form comes back as a PDF in documents. Pass manifest_id to fetch a form generated earlier.

{
  "carrier": "amazon",
  "action": "createmanifest",
  "params": {
    "client_id": "amzn1.application-oa2-client.abc123",
    "client_secret": "your-client-secret",
    "refresh_token": "Atzr|your-refresh-token",
    "application_id": "AmazonShipping_US",
    "carrier_code": "AMZN_US",
    "ship_name": "RocketShipIt",
    "ship_addr1": "123 Main St",
    "ship_city": "Whitehall",
    "ship_state": "MT",
    "ship_code": "59759",
    "ship_country": "US"
  }
}

Errors#

Amazon's errors are returned as errors with Amazon's code and message. Common ones:

Ineligible offerings from the rate request (weight or size limits, no coverage) are listed as Info errors so the missing services are explained.