Shipping your website orders with Amazon Shipping

What this is

Amazon Shipping is Amazon's courier service. You don't have to sell on Amazon to use it: it can deliver parcels for orders placed on your own website anywhere in India (Amazon's direct-integration guide).

Today you would have to copy each order into Amazon's portal by hand. Instead, your website will talk to Amazon directly through Amazon's official programming interface, the Selling Partner API (SP-API), Shipping API v2. You click Ship on an order in your admin; the website asks Amazon for a price, buys the shipment and gives you a printable label.

Every request we send is tagged AmazonShipping_IN so Amazon knows it's an India shipment. If the tag is missing, Amazon assumes the UK, so our code always sends it.

What you need to sign up for

You need two separate things: a shipper account (your deal with Amazon: prices, pickup address, billing) and a developer app (the keys our website uses to talk to Amazon). Here are the six steps:

1. Open an Amazon Shipping India account. Sign up at shipping.amazon.in → “Get started” with a Seller Central login (a new one is fine, you don't have to sell on Amazon). Enter your GST ID and how many parcels you ship per day. An Amazon account manager activates your rate card (your prices) and registers your pickup warehouse.
2. Register as a developer. Create a Solution Provider Portal account with a shared company email, then complete Developer Identity Verification (business documents and a point of contact).
3. Set up your developer profile and role. Choose “Private Developer” (you're connecting your own company) and the role “Amazon Logistics” (the role for own-website labels). Fill in the data-protection questionnaire carefully. Amazon reviews this in about 5 business days. Send the case number to your account manager to speed it up.
4. Create the app. Name it AmazonShipping_{YourName}, type SP-API, business entity Shipping, role Amazon Logistics, and answer “No” to the Restricted Data Token question. The portal then shows a client ID and client secret.
5. Authorise the app for yourself. Log in as an admin user, open Develop Apps → Edit App → Authorize, and copy the refresh token (it starts with Atzr|). Together these three values are the website's keys. (Self-authorisation guide)
6. Test and get signed off. We build and test get rates, buy, cancel and track, and produce a test label for Amazon to check. Your account manager then confirms your first real shipping date. (Test case guide)

How login works

Amazon uses Login with Amazon (LWA). Think of it like a hotel:

The website does this by itself. It remembers the room key and gets a new one a few minutes before it runs out. Nobody has to log in by hand. (Older Amazon guides mention AWS signatures. Those are no longer needed.)

Where requests go: India is in Amazon's Europe region, so the website uses

Switching between the two is a single setting (SPAPI_HOST). (SP-API endpoints)

How a label gets made

Clicking Ship on an order starts these steps:

1. 1

   Get rates

   The website sends the order details to Amazon and gets back the available services, with the price in rupees, the pickup time and the expected delivery date. If Amazon can't deliver to that pincode, it says so here.

   Order must supply: customer name, phone, address and 6-digit pincode; parcel weight and real box dimensions (made-up sizes aren't allowed); items with quantity and value; order total (used for insurance and the COD amount); whether it is cash on delivery. Your pickup address and GSTIN come from settings.

2. 2

   Buy shipment

   The chosen rate is purchased. This is the moment you are charged. It must happen within 10 minutes of getting the rates, or the quote expires and the website simply asks again.

   Order must supply: nothing new. It uses the chosen rate, the label format (PDF by default) and whether to collect cash on delivery.

3. 3

   Download label

   Amazon returns a 4×6 inch label (PDF, PNG or ZPL for thermal printers) and a tracking number. The website saves the file so you can print it. A lost label can be downloaded again at any time.

   Kept with the order: shipment ID, tracking ID, order/package reference.

4. 4

   Track

   The website can ask where the parcel is: picked up, in transit, out for delivery, delivered and so on. The full history is kept for 45 days.

   Needs: tracking ID and carrier ID (ATS in India), both saved at purchase.

5. 5

   Cancel (if needed)

   A shipment can be cancelled before pickup. In India it can also be cancelled while in transit, but not once it is out for delivery or delivered.

   Needs: the shipment ID saved at purchase.

Amazon tutorials: buy from a rate, track, cancel.

Testing without real money

There are two safe ways to test before any real parcel ships:

1. Our own local mock server (works today)

We built a small pretend version of Amazon that runs on our own computer. It answers like Amazon does, with India-style prices, a sample PDF label and tracking. Running node mock/server.mjs starts it at http://127.0.0.1:4010. No Amazon account is needed, so we can build and test everything now.

2. Amazon's sandbox (needs your app keys)

Amazon also has a practice environment, the sandbox. It runs the full get rates → buy → label → track → cancel flow with no charges and no pickups. It still needs the approved app and refresh token from steps 4–5 above. Its prices, service names and labels are fake and may not match India production.

Costs, limits and gotchas

• Price per parcel comes from your own negotiated rate card. Amazon has no public price list, so the website shows the price before you buy.
• Cash on delivery fee: ₹30 per parcel or 1.5% of the value, whichever is higher. Prepaid orders have no extra fee.
• Billing and COD payouts aren't publicly documented. Agree them with your account manager.
• Speed limit: about 5 requests per second by default. That's far more than a website needs.
• One box = one shipment. Multi-box orders need one label per box.
• Use real weights and box sizes. Made-up values aren't allowed.
• No separate pickup booking. The pickup slot comes with the rate and is based on the days and times you agreed with Amazon.
• Quotes expire after 10 minutes. The website re-asks automatically.
• “Access denied” errors usually mean the shipper account isn't active yet, has no rate card, or is missing the role. After adding a role you must authorise again and use the new refresh token.
• Print labels at the DPI they were requested at, or thermal labels print cut off. For an ordinary printer we use PDF 4×6 at 203 DPI.
• Dangerous goods (batteries, perfumes, aerosols) need separate approval from Amazon.
• The client secret must be renewed from time to time. Register a contact in the portal to get reminders.

Source: Amazon Shipping FAQ.

What we have built so far

A small, self-contained building block that can be plugged into your website once we know how your website is built:

• src/amazon/config: reads the private settings (keys, practice or live address, pickup address, GSTIN, label format) from a .env file and stops with a clear message if a key is missing.
• src/amazon/auth: handles the Login with Amazon “room key”. It fetches it, remembers it, and renews it 5 minutes before it expires.
• src/amazon/mappers: turns a website order into the exact form Amazon expects (addresses, box, items, GST, COD) and checks it for problems first.
• src/amazon/client: sends the five requests (get rates, buy, download label, track, cancel) with the right headers and turns Amazon's errors into readable messages.
• src/amazon/purchase: picks the rate (your chosen service, otherwise the cheapest), prepares the purchase in the right label format, and saves the label file as storage/labels/<trackingId>.pdf.
• mock/server.mjs: the pretend Amazon described above, for testing without accounts or money.

Each piece has automated tests. Still to do: connecting it to your website's admin, which depends on your answers below.

Questions we need you to answer

1. Do you already have an Amazon Shipping India account (rate card active, pickup warehouse registered), or a Seller Central / Solution Provider Portal login? Who is your Amazon Shipping account manager?
2. Is the business GST-registered? Which GSTIN should we use?
3. Pickup address: one warehouse or several? The exact registered address(es) and agreed pickup days/times.
4. Do you offer cash on delivery? Should the COD amount always equal the order total? How and how often does Amazon pay COD money to you?
5. Billing: how does Amazon charge you (prepaid wallet, monthly invoice, card)? Is there a credit limit that could block buying labels?
6. Which service: Standard only, or Express/Air too? Should you pick from the prices each time, or should the website always pick the cheapest?
7. Packaging data: does your website store product weights and box sizes? If not, what default box sizes and weights should we use?
8. Printer: an ordinary printer (PDF) or a thermal label printer (ZPL, 203 or 300 DPI)?
9. Do you sell any dangerous goods (batteries, perfumes, aerosols)?
10. Do you ever send multi-box orders? (Each box is a separate shipment and label.)
11. What is your website built with and hosted on (language, database, where files can be stored)?
12. Should customers see tracking on the website or get tracking emails, or is tracking in the admin enough for now?
13. If Amazon can't deliver to a pincode, should we use another courier or block the order?