What we do
Tools
Industries
Department
How we workLet's talk →
Home/AfterShip/Using the AfterShip API for Tracking and Labels
AfterShip

Tracking or Labels? Using the AfterShip API for the Job You Actually Have

AfterShip's developer docs cover two products. The Tracking API follows shipments across hundreds of carriers and pushes status changes to you. The Shipping API, which started life as Postmen, quotes rates and buys labels. They share an account and a key style, but you only need the one that matches what you're building.

First request on the Tracking API

Key: create one in the AfterShip admin's API key settings and send it in an as-api-key header. Older v4 code sends aftership-api-key instead, against the legacy URL.

URL and version: current versions are dated, so calls go to https://api.aftership.com/tracking/<version>/, with the version in the path. Pin one and move up deliberately.

First call: POST to /trackings with the tracking number. Add the carrier slug if you know it; AfterShip can detect the carrier when you don't.

Limit: 10 requests a second by default. X-RateLimit-Remaining and X-RateLimit-Reset tell you when to back off, and going over returns a 429.

AfterShip Tracking API and Shipping API, side by side

Tracking API

Where is it, and has anything gone wrong?

  • Register tracking numbers and read their checkpoint history.
  • Statuses come as a tag (InTransit, OutForDelivery, Exception, Delivered and so on) plus a more specific subtag.
  • Webhooks push each status change, so you don't poll.
Shipping API (formerly Postmen)

Which carrier, at what price, and the label

  • Quote one shipment against the carrier accounts you've connected.
  • Buy the label once your rule picks the winner: cheapest, fastest or a preferred carrier.
  • Does the job ShipEngine or EasyPost do elsewhere, inside the AfterShip account.

Stores answering "where's my order" need the Tracking API. Warehouses printing labels from their own system need the Shipping API. Plenty of builds use both.

Receiving AfterShip tracking webhooks safely

  1. 1

    Add the webhook URL

    In the admin's webhook settings, add your endpoint (up to 10 URLs) and pick the events. AfterShip sends a test POST first and only saves the URL when your endpoint answers 200.

  2. 2

    Recompute the HMAC

    Each request carries an aftership-hmac-sha256 header: a base64 HMAC-SHA256 of the raw body, keyed with your account's webhook secret. Compute it yourself and compare before trusting anything in the payload.

    Watch for: the raw body. Parsing and re-serializing the JSON first changes the bytes and the check fails.

  3. 3

    Answer fast, work later

    Return 200 straight away and queue the event for processing. Store an ID for each event you handle, so a repeat delivery gets skipped rather than acted on twice.

  4. 4

    Act on the subtag

    A Delivered tag might trigger a review request. An Exception subtag like a failed delivery attempt should reach a person or the customer. Treat tag and subtag as strings, since AfterShip can add new values.

Tracking data that arrives and still changes nothing

Webhooks logged, never read

How you'll know: Exceptions are visible in AfterShip's dashboard and in your logs, and the customer still finds out first.

Fix: Send the event where someone works: a ticket in the help desk, a flag on the order, or a message to the customer for the subtags you choose.

One integration burning the whole per-second budget

How you'll know: A backfill of old tracking numbers starts returning 429s and live order creation fails with it.

Fix: Put both through one paced queue and keep backfills slower than live traffic.

Tracking that never links back to the order

How you'll know: A webhook arrives and nothing can say which order or customer it's about.

Fix: Send your order ID and number when you create the tracking, so every update comes back already tied to it.

Questions people ask

What is AfterShip's API?

Two developer products under one AfterShip account: the Tracking API, which follows shipments across hundreds of carriers and sends webhooks as status changes, and the Shipping API, for multi-carrier rates and labels.

Is Postmen the same thing as AfterShip?

Postmen was AfterShip's standalone shipping API. It's now the AfterShip Shipping API, though the Postmen name still turns up in older docs and developer threads.

How do I get an AfterShip API key?

Create it in your AfterShip admin's API key settings. No OAuth flow is needed: the key goes in the as-api-key header. For extra protection, AfterShip also supports signing requests with an API secret (AES or RSA).

How many carriers does AfterShip's API support?

The Tracking API covers several hundred carriers worldwide. The Shipping API supports a smaller set for rates and labels, limited to the carrier accounts you connect.

How do I verify an AfterShip webhook?

Recompute a base64 HMAC-SHA256 of the raw request body with your webhook secret and compare it to the aftership-hmac-sha256 header. Reject the request if they don't match.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.