Skip to content
Veeqo, An Amazon company Developers
Login Signup

Shipping Amazon Orders with the Rate Shopping API

This guide walks through the end-to-end process of getting shipping rates and purchasing labels for Amazon orders using the Veeqo Rate Shopping API. It covers both domestic (US to US) and international (US to other countries) shipments.

Prerequisites

Before making your first request, ensure you have the following:

  1. A Veeqo API key for authentication
  2. The Amazon order number (e.g., 112-4737182-6879466)
  3. The line item IDs from SP-API — the OrderItemId for each item in the order (see Retrieving the Amazon Line Item ID)
  4. A ship-from address (your warehouse or fulfillment center)

Overview

The shipping flow consists of three steps:

1. Get Rates  →  2. Book Shipment  →  3. Retrieve Label & Documents

Each step corresponds to a single API call. The sections below walk through each one with complete request and response examples.

Step 1: Get Rates

Request available shipping rates by providing package details, addresses, and order information.

Endpoint: POST /shipping/api/v1/rates

Domestic Amazon Order (US to US)

For domestic shipments, provide the order details along with channel_items to enable Amazon Buy Shipping protections. 

curl -X POST 'https://api.veeqo.com/shipping/api/v1/rates' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
  "to_address": {
    "name": "Sarah Johnson",
    "phone": "+13125551234",
    "line1": "233 S Wacker Dr",
    "town": "Chicago",
    "postcode": "60606",
    "country_code": "US",
    "county": "IL"
  },
  "from_address": {
    "name": "My Warehouse",
    "company": "My Store Inc",
    "phone": "+12065551234",
    "line1": "410 Terry Ave N",
    "town": "Seattle",
    "postcode": "98109",
    "country_code": "US",
    "county": "WA"
  },
  "parcels": [
    {
      "weight": 1.5,
      "weight_unit": "lb",
      "height": 8.0,
      "width": 8.0,
      "length": 8.0,
      "dimension_unit": "in"
    }
  ],
  "is_amazon_order": true,
  "customer_reference": "112-4737182-6879466",
  "estimated_value": "25.00",
  "currency_code": "USD",
  "seller_display_name": "My Store Name",
  "channel_items": [
    {
      "remote_id": "148539107022961",
      "quantity": 1,
      "value": "25.00",
      "currency_code": "USD"
    }
  ]
}'

Key Fields for Domestic Amazon Orders

Field Description
is_amazon_order Must be true to identify this as an Amazon order
customer_reference The Amazon order number — required for Buy Shipping protections
estimated_value Total shipment value, used for insurance and protections
seller_display_name Your store name, printed on the shipping label
channel_items[].remote_id The OrderItemId from SP-API (see Retrieving the Amazon Line Item ID)
channel_items[].quantity Quantity being shipped for this line item
channel_items[].value Item value, used for protections calculation

International Amazon Order (US to Other Countries)

International shipments require additional fields for customs declarations. Each channel_item must include an asin, and customs-related fields such as description, tariff_code, and country_of_manufacture are recommended. 

curl -X POST 'https://api.veeqo.com/shipping/api/v1/rates' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
  "to_address": {
    "name": "Marie Leclerc",
    "phone": "+33140205050",
    "line1": "15 Rue de Rivoli",
    "town": "Paris",
    "postcode": "75001",
    "country_code": "FR"
  },
  "from_address": {
    "name": "My Warehouse",
    "company": "My Store Inc",
    "phone": "+12065551234",
    "line1": "410 Terry Ave N",
    "town": "Seattle",
    "postcode": "98109",
    "country_code": "US",
    "county": "WA"
  },
  "parcels": [
    {
      "weight": 1.0,
      "weight_unit": "lb",
      "height": 6.0,
      "width": 6.0,
      "length": 6.0,
      "dimension_unit": "in"
    }
  ],
  "is_amazon_order": true,
  "customer_reference": "405-1234567-8901234",
  "estimated_value": "50.00",
  "currency_code": "USD",
  "seller_display_name": "My Store Name",
  "contents": "Consumer Electronics",
  "country_of_origin": "US",
  "incoterms": "DAP",
  "channel_items": [
    {
      "remote_id": "148539107022961",
      "asin": "B08N5WRWNW",
      "quantity": 1,
      "value": "50.00",
      "currency_code": "USD",
      "description": "Wireless Headphones",
      "weight": 0.3,
      "weight_unit": "kg",
      "tariff_code": "8518.30.20",
      "country_of_manufacture": "CN"
    }
  ]
}'

Additional Fields for International Shipments

Field Description Required?
channel_items[].asin Amazon ASIN for the product Yes
channel_items[].description Item description for customs (max 40 characters) Recommended
channel_items[].weight Item weight (total for this line, not per-unit) Recommended
channel_items[].weight_unit Weight unit (defaults to kg) Recommended
channel_items[].tariff_code HS/tariff code for customs classification Recommended
channel_items[].country_of_manufacture ISO country code where the item was manufactured Recommended
contents General description of package contents Recommended
country_of_origin Default country of manufacture for all items Optional
incoterms Delivery terms — DAP (buyer pays duties) or DDP (seller pays duties) Optional

Note: If weight is not provided on individual channel items, the parcel weight is distributed evenly across all items. If country_of_manufacture is omitted, it defaults to the ship-from address country.

Understanding the Rates Response

The response contains a list of available shipping options:

{
  "quotes": [
    {
      "rate_id": "amazon_shipping_v2-df3f52c6-643e-4959-b802-f60ca1df42bb",
      "service_name": "USPS Ground Advantage (1 - 70 lb)",
      "carrier_id": "USPS",
      "service_carrier": "usps",
      "currency": "USD",
      "total_charge": "6.41",
      "base_rate": "6.41",
      "protected": true,
      "protections": ["CLAIMS_PROTECTED"],
      "service_id": "USPS_PTP_GAH",
      "charges": [ ... ],
      "shipping_service_options": [ ... ]
    }
  ],
  "remote_shipment_id": "prb8a99eb17",
  "request_token": "amzn1.rq.abc123...",
  "expires_at": "2025-12-11T18:29:18.234Z"
}

The following values from the response are needed for Step 2:

Field Description
quotes[].rate_id The rate identifier — use this as rate_id when booking
remote_shipment_id The shipment identifier — required for booking
expires_at Expiration timestamp — the booking must be completed before this time

Buy Shipping Protections

For Amazon orders, rates may include Buy Shipping protections when channel_items are provided:

  • "protected": true indicates the rate includes Amazon Buy Shipping protections
  • "protections": ["CLAIMS_PROTECTED"] indicates coverage for A-to-Z claims

Buy Shipping protections are available for both domestic and international Amazon shipments.

Step 2: Book the Shipment

Purchase a shipping label using a rate from Step 1.

Endpoint: POST /shipping/api/v1/shipments 

curl -X POST 'https://api.veeqo.com/shipping/api/v1/shipments' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
  "label_format": "PDF",
  "shipments": [
    {
      "remote_shipment_id": "prb8a99eb17",
      "rate_id": "amazon_shipping_v2-df3f52c6-643e-4959-b802-f60ca1df42bb"
    }
  ]
}'

The remote_shipment_id and rate_id are the values saved from the rates response. The shipments parameter must be an array, even when booking a single shipment.

Adding Optional Services

Optional services from the shipping_service_options in the rates response can be included in the booking request: 

{
  "label_format": "PDF",
  "shipments": [
    {
      "remote_shipment_id": "prb8a99eb17",
      "rate_id": "amazon_shipping_v2-df3f52c6-643e-4959-b802-f60ca1df42bb",
      "value_added_service__VAS_GROUP_ID_CONFIRMATION": "SIGNATURE_CONFIRMATION",
      "liability_amount": 100.00
    }
  ]
}

Understanding the Book Response

{
  "successful": {
    "prb8a99eb17": {
      "tracking_number": "9341920111411169517859",
      "carrier_id": "USPS",
      "service_name": "USPS Ground Advantage",
      "label_format": "PDF",
      "label_content": "JVBERi0xLjQK...",
      "total_charge": { "value": 6.41, "unit": "USD" },
      "documents": [
        {
          "type": "COMMERCIAL_INVOICE",
          "content": "JVBERi0xLjQK..."
        }
      ]
    }
  },
  "failed": {}
}
Field Description
tracking_number The carrier tracking number for the shipment
label_content Base64-encoded shipping label — decode to obtain the PDF, PNG, or ZPL file
documents Shipping documents (e.g., commercial invoices) returned as base64. Present for international shipments when the carrier provides them

Note: The documents array is only included when the carrier returns shipping documents alongside the label. These documents are also stored for later retrieval via presigned URLs (see Step 3).

Step 3: Retrieve Labels and Documents

Labels and documents can be retrieved at any time after booking for reprinting or record-keeping.

Get Shipment Details

Endpoint: GET /shipping/api/v1/shipments/:id 

curl -X GET 'https://api.veeqo.com/shipping/api/v1/shipments/prb8a99eb17' \
-H 'x-api-key: YOUR_API_KEY'

Response:

{
  "remote_shipment_id": "prb8a99eb17",
  "tracking_number": "9341920111411169517859",
  "carrier": "amazon_shipping_v2",
  "service_name": "USPS Ground Advantage",
  "label_url": "/shipping/api/v1/shipments/prb8a99eb17/label.pdf",
  "documents": [
    {
      "type": "COMMERCIAL_INVOICE",
      "url": "https://s3.amazonaws.com/..."
    }
  ]
}
  • label_url provides a direct link to download the shipping label
  • documents[].url provides presigned S3 download URLs, each valid for 1 hour

Download the Label

# Download the label as a PDF file
curl -X GET 'https://api.veeqo.com/shipping/api/v1/shipments/prb8a99eb17/label.pdf' \
-H 'x-api-key: YOUR_API_KEY' \
-o label.pdf

# Or request a redirect to a presigned URL
curl -X GET 'https://api.veeqo.com/shipping/api/v1/shipments/prb8a99eb17/label.pdf?redirect=true' \
-H 'x-api-key: YOUR_API_KEY'

Supported label formats: pdf, png, zpl, jpeg.

Download a Shipping Document

curl -X GET 'https://api.veeqo.com/shipping/api/v1/shipments/prb8a99eb17/documents/COMMERCIAL_INVOICE' \
-H 'x-api-key: YOUR_API_KEY' \
-L -o commercial_invoice.pdf

This endpoint returns a 302 redirect to a presigned S3 URL valid for 1 hour. Use the -L flag (or equivalent in your HTTP client) to follow the redirect.

Cancelling a Shipment

To void a shipping label and request a refund:

Endpoint: DELETE /shipping/api/v1/shipments/:id 

curl -X DELETE 'https://api.veeqo.com/shipping/api/v1/shipments/prb8a99eb17' \
-H 'x-api-key: YOUR_API_KEY'

Returns 204 No Content on success. Refund eligibility depends on carrier policies.

Retrieving the Amazon Line Item ID

The remote_id field in channel_items corresponds to the Amazon OrderItemId. This value is obtained by calling the SP-API GetOrderItems endpoint: 

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/{orderId}/orderItems

Example response (simplified):

{
  "OrderItems": [
    {
      "OrderItemId": "148539107022961",
      "ASIN": "B08N5WRWNW",
      "SellerSKU": "MY-SKU-001",
      "QuantityOrdered": 1,
      "ItemPrice": {
        "Amount": "25.00",
        "CurrencyCode": "USD"
      }
    }
  ]
}

SP-API to Rate Shopping API Field Mapping

SP-API Field Rate Shopping API Field Example
OrderItemId channel_items[].remote_id "148539107022961"
ASIN channel_items[].asin "B08N5WRWNW"
QuantityOrdered channel_items[].quantity 1
ItemPrice.Amount channel_items[].value "25.00"
ItemPrice.CurrencyCode channel_items[].currency_code "USD"

For complete SP-API documentation, see the Amazon SP-API Orders reference.

Quick Reference: Domestic vs International

Field Domestic (US → US) International (US → Other)
is_amazon_order true true
customer_reference Amazon order number Amazon order number
channel_items[].remote_id Required Required
channel_items[].asin Optional Required
channel_items[].description Optional Recommended
channel_items[].weight Optional Recommended
channel_items[].tariff_code Optional Recommended
channel_items[].country_of_manufacture Optional Recommended
contents Optional Recommended
incoterms Not applicable Optional
Buy Shipping Protections Available Available
Shipping Documents (e.g., commercial invoice) Not typically returned Returned when applicable

Troubleshooting

Issue Cause Resolution
No Buy Shipping protections on rates Missing is_amazon_order, customer_reference, or channel_items Ensure all three fields are provided in the rates request
"Rate quote has expired" error on booking The rate was not booked before expires_at Request new rates and book promptly
Booking fails for international Amazon order Missing asin on channel_items Include the ASIN for each channel item on international orders
No rates returned Invalid addresses, unsupported destination, or carrier restrictions Verify addresses and check unavailable_quotes in the response for specific reasons
channel_items validation error Missing remote_id for Amazon orders Retrieve the OrderItemId from SP-API and pass it as remote_id
Documents not available immediately after booking Documents are stored asynchronously Wait a few seconds and retry the shipment details or document download request