AfterShip helps eCommerce businesses to update and manage their shipment with efficiency.

You can seamlessly manage tracking with AfterShip's Tracking API and use AfterShip's post-purchase services from the admin portal. Or you can store the tracking data through API and webhook, and customize the post-purchase services yourself.

This QUICKSTART guide intends to walk you through 3 common scenarios, and hopefully, after this journey, you would know how to use AfterShip to create & manage your tracking.


1. What's tracking?

Tracking refers to shipment-related information, including a carrier's name, tracking number provided by the carrier, and checkpoints.

For all fields consisting 'tracking,' please refer to Tracking Object


2. Get the API key

AfterShip verifies a user's request by adding an aftership-api-key in the header. So you shall get the aftership-api-key first.

Enter settings, you can find a default API key.

You can generate different API keys for other projects.


3. Common scenarios


Scenario 1. Create tracking


Use POST API https://api.aftership.com/v4/trackings

Post Tracking API Doc

curl --location --request POST 'https://api.aftership.com/v4/trackings' \
--header 'aftership-api-key: your aftership api key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tracking": {
        "tracking_number": "9405511202575421535949",
        "slug": "usps"
    }
}'

When creating a tracking event, we suggest you provide both the tracking number and other courier information for us.

But if you don't have such info, you can skip it, and we will try to detect the courier for you.

Here are 3 ways to provide the courier's info

1 . If you know the slug of a specific courier, please fill the slug field (e.g., dhl-germany).

You could refer to AfterShip's Courier List. Send the Courier Slug (courier's name) accurately according to the List (Column A of the list).


2 . If you know the courier group but are unsure about the slug, please fill the slug_group field.

You could refer to AfterShip's Slug-Groups List , AfterShip will detect tracking that belongs to the slug group.


3 . If you don't know the courier, you can skip this field. We will detect the courier for you.

When auto-detecting the courier, we will refer to your Preferred Courier List that you set on our admin portal.

So we suggest you activate your commonly-used couriers on settings. This will help us map the right courier.


For some couriers, it's mandatory to fill some additional fields for tracking; else your tracking will fail to create.

Please call our Get all couriers API to get the mandatory fields.


Scenario 2 . Update existing tracking


Use API https://developers.aftership.com/reference/trackings#put-trackings-slug-tracking_number

If you want to correct an inaccurate tracking courier, update order information, or add extra information for an existing tracking, you can use the 'Update API'.


Scenario 3. Getting updates on the tracking


1 . Via webhook

AfterShip can push notifications to you for every tracking update via Webhook. With it, you can store all the tracking details and build up your own tracking page.

To set up your webhook, enter settings to fill in your webhook URL and save it.

You can add multiple webhook URLs, and we will push notifications to all those URLs.


Webhook secret

For security concerns, Webhook includes a signature for verification.

Each webhook request includes an aftership-hmac-sha256 header. The signature is a base64-encoded HMAC generated using the sha256 algorithm with webhook request body and the webhook secret of your account.

Sample encrypted signature (nodes)

const crypto = require('crypto');
const WEBHOOK_SECRET = "....."; // your webhook secret

function generateSignature(requestBodyString) {
    return crypto
        .createHmac('sha256', WEBHOOK_SECRET)
        .update(requestBodyString, 'utf8', 'hex')
        .digest('base64');
}

Sample webhook body

{
  "event_id": "bca2a741-8613-4694-bfb4-2ceb0016ee4f",
  "event": "tracking_update",
  "is_tracking_first_tag": true,
  "msg": {
    "id": "n33xyn2b61cm3kosdtnvu00e",
    "tracking_number": "9405516902697649303570",
    "title": "9405516902697649303570",
    "note": null,
    "origin_country_iso3": "USA",
    "destination_country_iso3": "USA",
    "courier_destination_country_iso3": "USA",
    "shipment_package_count": null,
    "active": true,
    "order_id": null,
    "order_id_path": null,
    "order_date": null,
    "customer_name": null,
    "source": "web",
    "emails": [
      "[email protected]"
    ],
    "smses": [],
    "subscribed_smses": [],
    "subscribed_emails": [],
    "android": [],
    "ios": [],
    "return_to_sender": false,
    "custom_fields": {},
    "tag": "InTransit",
    "subtag": "InTransit_003",
    "subtag_message": "Arrival scan",
    "tracked_count": 1,
    "expected_delivery": "2021-05-17",
    "signed_by": null,
    "shipment_type": "Priority Mail",
    "created_at": "2021-05-17T09:05:29+00:00",
    "updated_at": "2021-05-17T09:05:31+00:00",
    "slug": "usps",
    "unique_token": "deprecated",
    "path": "deprecated",
    "shipment_weight": null,
    "shipment_weight_unit": null,
    "delivery_time": 5,
    "last_mile_tracking_supported": true,
    "language": null,
    "shipment_pickup_date": "2021-05-13T18:10:00",
    "shipment_delivery_date": null,
    "last_updated_at": "2021-05-17T09:05:31+00:00",
    "checkpoints": [
      {
        "location": "BOCA RATON, FL, 33487, USA, United States",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": "FL",
        "city": "BOCA RATON",
        "zip": "33487",
        "message": "Shipping Label Created, USPS Awaiting Item",
        "coordinates": [],
        "tag": "InfoReceived",
        "subtag": "InfoReceived_001",
        "subtag_message": "Info Received",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-13T13:04:00",
        "slug": "usps",
        "raw_tag": "GX"
      },
      {
        "location": "BOCA RATON, FL, 33487, USA, United States",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": "FL",
        "city": "BOCA RATON",
        "zip": "33487",
        "message": "Accepted at USPS Origin Facility",
        "coordinates": [],
        "tag": "InTransit",
        "subtag": "InTransit_002",
        "subtag_message": "Acceptance scan",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-13T18:10:00",
        "slug": "usps",
        "raw_tag": "OA"
      },
      {
        "location": "WEST PALM BEACH FL DISTRIBUTION CENTER",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": null,
        "city": "WEST PALM BEACH FL DISTRIBUTION CENTER",
        "zip": null,
        "message": "Arrived at USPS Regional Origin Facility",
        "coordinates": [],
        "tag": "InTransit",
        "subtag": "InTransit_003",
        "subtag_message": "Arrival scan",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-13T19:25:00",
        "slug": "usps",
        "raw_tag": "10"
      },
      {
        "location": "WEST PALM BEACH FL DISTRIBUTION CENTER",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": null,
        "city": "WEST PALM BEACH FL DISTRIBUTION CENTER",
        "zip": null,
        "message": "Departed USPS Regional Origin Facility",
        "coordinates": [],
        "tag": "InTransit",
        "subtag": "InTransit_007",
        "subtag_message": "Departure Scan",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-14T00:25:00",
        "slug": "usps",
        "raw_tag": "10"
      },
      {
        "location": "FAYETTEVILLE NC DISTRIBUTION CENTER ANNEX",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": null,
        "city": "FAYETTEVILLE NC DISTRIBUTION CENTER ANNEX",
        "zip": null,
        "message": "Arrived at USPS Regional Destination Facility",
        "coordinates": [],
        "tag": "InTransit",
        "subtag": "InTransit_003",
        "subtag_message": "Arrival scan",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-15T13:06:00",
        "slug": "usps",
        "raw_tag": "10"
      },
      {
        "location": "FAYETTEVILLE NC DISTRIBUTION CENTER ANNEX",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": null,
        "city": "FAYETTEVILLE NC DISTRIBUTION CENTER ANNEX",
        "zip": null,
        "message": "Departed USPS Regional Facility",
        "coordinates": [],
        "tag": "InTransit",
        "subtag": "InTransit_007",
        "subtag_message": "Departure Scan",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-16T05:52:00",
        "slug": "usps",
        "raw_tag": "T1"
      },
      {
        "location": "HOLLY RIDGE, NC, 28445, USA, United States",
        "country_name": "United States",
        "country_iso3": "USA",
        "state": "NC",
        "city": "HOLLY RIDGE",
        "zip": "28445",
        "message": "Arrived at Post Office",
        "coordinates": [],
        "tag": "InTransit",
        "subtag": "InTransit_003",
        "subtag_message": "Arrival scan",
        "created_at": "2021-05-17T09:05:31+00:00",
        "checkpoint_time": "2021-05-17T03:45:00",
        "slug": "usps",
        "raw_tag": "07"
      }
    ],
    "order_promised_delivery_date": null,
    "delivery_type": null,
    "pickup_location": null,
    "pickup_note": null,
    "tracking_account_number": null,
    "tracking_origin_country": null,
    "tracking_destination_country": null,
    "tracking_key": null,
    "tracking_postal_code": null,
    "tracking_ship_date": null,
    "tracking_state": null,
    "courier_tracking_link": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9405516902697649303570",
    "first_attempted_at": null,
    "courier_redirect_link": "https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels=9405516902697649303570%2C"
  },
  "ts": 1621242332
}

2 . Via API

To retrieve the latest checkpoint, use GET API https://api.aftership.com/v4/last_checkpoint/:slug/:tracking_number

NOTE: GET API limits 10 requests per second and it will show errors if exceeded. Hence, it's not suggested to use the GET API to build your own tracking page.

Sample Request

curl --location --request GET 'https://api.aftership.com/v4/last_checkpoint/usps/9400111206371469383602' \
--header 'aftership-api-key: your aftership api key'

Sample Response

{
    "meta": {
        "code": 200
    },
    "data": {
        "id": "iekfrf6rd9slzkotfefv702j",
        "tracking_number": "9400111206371469383602",
        "slug": "usps",
        "tag": "InTransit",
        "subtag": "InTransit_003",
        "subtag_message": "Arrival scan",
        "checkpoint": {
            "slug": "usps",
            "created_at": "2021-05-18T02:37:26+00:00",
            "checkpoint_time": "2021-05-17T19:49:00",
            "city": "CHICAGO IL NETWORK DISTRIBUTION CENTER",
            "coordinates": [],
            "country_iso3": "USA",
            "country_name": "USA",
            "message": "Arrived at USPS Regional Origin Facility",
            "state": null,
            "tag": "InTransit",
            "subtag": "InTransit_003",
            "subtag_message": "Arrival scan",
            "zip": null
        }
    }
}