Apple Wallet Order Tracking
Apple Wallet Order Tracking lets shoppers add an order to the Wallet app on their iPhone, where they can see the order contents and follow its delivery progress. This page explains which fields you need to send through the Commerce API so that the Wallet order pass is complete.
1. Prerequisites
| Prerequisite | Details |
|---|---|
| Order source | Orders must be imported through a connected eCommerce store, the Commerce API, or an order CSV. Shipments created through the Tracking API alone cannot use Apple Wallet. |
| Enable the add-on | Turn it on in the AfterShip Tracking admin under Add-ons > Apple Order Tracking. Only the Admin, Owner, or Member(s) of the organization can enable it. |
| Configure the Order Page | Under Add-ons > Apple Order Tracking > Apple Wallet Order Page, select the Order source and fill in the store name, logo, store URL, and order management page URL. The pass cannot be generated without this configuration. |
| Scope | Once enabled, the widget applies to all connected stores and orders in the organization. It cannot be turned on per store. |
For the admin configuration steps, see the Help Center article Set up Apple Wallet Order Tracking With AfterShip Tracking.
2. Shipment Information Requires Reference Mode
The shipment section of the Wallet pass — courier, tracking number, estimated delivery, delivered time, and delivery status — comes from the AfterShip tracking record, not from the fields you write on the fulfillment.
If you use Inline Mode and only provide a tracking_number, AfterShip does not create a tracking task, and the entire shipment section is missing from the pass. Shoppers see the items and the amounts, but not where the parcel is.
In short: create the tracking with the Tracking API first, then reference it from the fulfillment through trackings[].id.
For the full comparison of the two modes, see Tracking Modes: Reference and Inline.
3. Field Mapping
3.1 Line Items
| Commerce API field | Requirement | How it appears on the pass |
|---|---|---|
| items | Required | Without items, no item list is shown on the pass |
| items.*.product_title | Required | Product name |
| items.*.quantity | Required | Quantity |
| items.*.image_urls | Recommended | The first URL in the array is used as the product image. Without it, a letter placeholder is shown |
| items.*.unit_price | Recommended | Unit price |
| items.*.sku | Recommended | SKU |
| items.*.product_variant_title | Recommended | Variant information |
3.2 Payment Summary
| Commerce API field | Requirement | How it appears on the pass |
|---|---|---|
| order_total | Required | Without it, the entire payment summary is omitted from the pass |
| currency | Required | Currency of all amounts |
| subtotal | Recommended | The Subtotal row. Shown as 0 when omitted |
| discount_total | Recommended | The Discounts row, shown as a negative amount. Shown as 0 when omitted |
| shipping_total | Recommended | The Shipping row. Shown as 0 when omitted |
| tax_total | Recommended | The Taxes row. When taxes_included is true, taxes are not listed separately and item prices are shown tax-inclusive instead |
3.3 Order Status
| Commerce API field | Requirement | Details |
|---|---|---|
| status | Required | Mapped to one of the three Wallet order states: open, completed, or cancelled |
| number | Recommended | Shown as the order number |
| source_created_at | Strongly recommended | See Known Limitations — without it, the Apple Wallet analytics report has no data |
3.4 Shipment Section
This section does not come from fields on the fulfillment. It comes from the tracking referenced through Reference Mode.
| Content on the pass | Source |
|---|---|
| Courier name | The slug of the tracking |
| Tracking number | The tracking_number of the tracking |
| Delivery status and description | The latest shipment status retrieved by AfterShip |
| Estimated delivery | The AfterShip estimated delivery date |
| Delivered time | The delivery timestamp from the tracking checkpoints |
| Which items are in this parcel | The relationship between the fulfillment line_items and the order items |
3.5 Merchant Information (Not Set Through the API)
The store name, logo, store URL, order management page URL, support email, and support phone number on the pass all come from the Add-ons > Apple Order Tracking > Apple Wallet Order Page configuration in the admin. They cannot be passed through the Commerce API.
4. Complete Example
Step 1 — create the order
preparing...
Step 2 — create the tracking with the Tracking API
preparing...
Step 3 — create the fulfillment and reference that tracking
preparing...
With these three steps done, a shopper who taps Track with Apple Wallet on the Branded Tracking Page, in an email, or in an SMS receives a complete order pass.
5. Known Limitations
5.1 Item details are not downloaded when the page is looked up by tracking number
Because of privacy requirements, when a shopper opens the tracking page using only a tracking number, the order number and the item details — including images and prices — are not written into the Wallet pass, even if you sent all of the fields described above.
For item information to appear, the link you send to shoppers must carry both the order number and the email address:
In email templates, use the ORDER_URL merge tag rather than TRACKING_URL.
5.2 The analytics report depends on the order creation time
The Apple Wallet analytics report attributes events by order creation time. If an order has no creation time, Wallet events are still ingested, but the report shows no data for them.
Always send source_created_at when creating an order.
5.3 Device and operating system requirements
The Track with Apple Wallet button requires iOS 17+ or macOS 14+. Order passes can only be viewed and tracked on iPhone. For the full device and browser support matrix, see the Help Center article linked above.
5.4 The button disappears once the order has been added
After an order has been added to Apple Wallet from a supported device, the button is removed from the tracking page and from subsequent emails and SMS messages. This is expected behavior.