Tracking Modes: Reference and Inline
In short: if you need tracking checkpoints, notifications, the Branded Tracking Page, webhooks, or Apple Wallet — any one of them — you must use Reference Mode. Inline Mode only records the tracking number on the order; AfterShip does not track it.
Starting from version 2026-01, the trackings array on a fulfillment supports two mutually exclusive modes. Choosing the wrong mode could be one of the common issue when integrating with the Commerce API, you may use this guide for the troubleshooting.
1. How to Use Each Mode
Reference Mode (Recommended)
Create the tracking with the Tracking API first, then reference its ID from the fulfillment.
Step 1 — create the tracking with the Tracking API:
preparing...
Here id is an identifier you define yourself. If you omit it, AfterShip generates one and you need to read it from the response.
Step 2 — reference it when creating the fulfillment:
preparing...
In this mode the courier, tracking number, ship date, custom fields and other shipment attributes all come from the tracking record in the Tracking API. Passing any other field inside trackings[] has no effect.
Inline Mode
Provide the tracking number directly, without creating a tracking:
preparing...
This mode does not create a tracking task. The tracking number is stored as supplementary information on the order only. AfterShip does not retrieve checkpoints from the courier, so there is no shipment status, no notification is triggered, and the shipment does not appear in your Tracking dashboard.
Because no tracking task is created, this mode does not consume your tracking quota.
Inline Mode fits exactly one scenario: you already track the parcel somewhere else, and you only want the tracking number stored alongside the order for reference.
2. Capability Comparison
| Capability | Reference Mode | Inline Mode |
|---|---|---|
| Tracking checkpoints | Yes | No |
| Visible in the Tracking dashboard | Yes | No |
| Email / SMS shipment notifications | Yes | No |
| Shipment status on the Branded Tracking Page | Yes | No |
| Webhook events | Yes | No |
| Estimated Delivery Date (EDD) | Yes | No |
| Shipment details in the Apple Wallet order pass | Yes | No |
| Tracking number recorded on the order | Yes | Yes |
| Consumes tracking quota | Yes | No |
3. Rules
- Within a single tracking object,
idandtracking_numbercannot both be present. The request is rejected if they are. - Reference Mode requires only
id. - In Inline Mode,
tracking_numberis required andslugis optional. - You can mix objects of both modes inside the same
trackingsarray. PATCH /fulfillments/{id}replaces the wholetrackingsarray — it does not merge. Send the complete list you want to keep; anything omitted is removed.
4. Response Differences
GET endpoints return the trackings in the same shape you wrote them:
| How it was written | What is returned |
|---|---|
| Reference Mode | Only id — the custom ID you passed in |
| Inline Mode | tracking_number and slug; id is not returned |
The AfterShip internal tracking UUID is never exposed through the Commerce API.
5. Troubleshooting: the Fulfillment Was Created, but the Shipment Is Not in the Tracking Dashboard
This is usually one of the following two causes.
Cause 1: You are using Inline Mode
Check the request body you posted:
- You sent
trackings[].id— this is Reference Mode, and the shipment should be visible. - You sent
trackings[].tracking_number— this is Inline Mode, and not seeing the shipment is expected. Switch to Reference Mode.
The same cause explains most reports of "the API returned 201 but no webhook fired" or "my customer did not receive the notification email".
Cause 2: The store has not been activated yet
Every Commerce API resource belongs to a store. After you create a store, you still need to contact the AfterShip support team or your customer success manager to configure and enable the Tracking feature for that store. This is a separate step from any AfterShip product you have already subscribed to, and it is easy to miss.
Until it is done, your data does not flow into AfterShip Tracking. See API Quick Start — Activating the store for the full instructions.
6. Upgrading From 2025-07 or Earlier
In 2025-07 and earlier, tracking_number inside trackings[] was required, and the Commerce API created the tracking for you automatically.
Starting from 2026-01 that automatic creation has been removed. The exact same request body creates a tracking on the older versions, but is treated as Inline Mode — a record only — on 2026-01 and 2026-07.
If new shipments stopped appearing in your Tracking dashboard after an upgrade, and notifications and webhooks went quiet, this is why. The fix is to switch to Reference Mode.