Adopting the Commerce API Alongside the Tracking API

This page is for users who currently use only the Tracking API and want to start using features that need order information — Apple Wallet Order Tracking, order-level notifications, order lookup on the Branded Tracking Page, and so on.

---

1. Common Misconception: No Need to Drop the Tracking API

A common wrong assumption is that adopting the Commerce API means replacing all of your Tracking API calls, which is not true.

Since 2026-01, the Commerce API no longer creates trackings on its own. Creating a tracking remains the job of the Tracking API. The Commerce API owns the layer above it: the order and the fulfillment.

So this is an additive change. Your existing Tracking API calls stay exactly as they are; you add one Commerce API call before them and one after, to attach the shipment to an order.

2. Steps

Step	Call	New?
0	Create a store, then have the support team activate it	New — see Activating the store
1	POST /commerce/2026-07/orders to create the order	New
2	POST /tracking/{version}/trackings to create the tracking	You already do this — no change
3	POST /commerce/2026-07/fulfillments to create the fulfillment, referencing the tracking from step 2 through trackings[].id	New

Steps 2 and 3 can be swapped: you may create a fulfillment without trackings first, then attach the tracking later with PATCH /fulfillments/{id}. However, PATCH replaces the whole trackings array, so with multiple parcels you must send the complete list.

For sample request bodies, see the complete example on the Apple Wallet page — the three steps are the same.

3. Where Your Current Fields Go

Every field marked "unchanged" below requires no modification at all; keep sending it through the Tracking API.

What you send to the Tracking API today	After adopting the Commerce API
tracking_number / slug	Unchanged
custom_fields	Unchanged
tracking_ship_date / shipment_type and other shipment attributes	Unchanged
emails / smses (recipients)	Unchanged. We also recommend setting customer.emails and customer.phones on the order, since order-level features read the contacts from the order
title (order name)	Unchanged. At the order level this is carried by order.number
order_id	Unchanged. At the order level this is carried by order.id
-	New: order.status, order.currency, order.order_total, order.items[], order.source_created_at
-	New: fulfillment.line_items[], which states the order items contained in this parcel

For what each order field drives, see the Order API Reference and the individual scenario pages in this section.

4. Frequently Asked Questions

Will this create duplicate shipments or double charges?

No. Step 3 uses Reference Mode (trackings[].id), which references the tracking already created in step 2. It does not create a second one and does not consume additional tracking quota.

Conversely, if step 3 accidentally uses Inline Mode — passing tracking_number directly — you end up with a record that has no tracking checkpoints. This is the most common mistake during adoption. See Tracking Modes: Reference and Inline.

What about trackings that already exist?

No backfill is needed. Adoption takes effect going forward. Trackings previously created through the Tracking API alone remain valid and keep working as before.

Can I adopt this for only part of my orders?

Yes. Commerce API orders and Tracking API shipments coexist, so you can start with a single business line as a pilot.

5. Adoption Checklist

• The store has been created, and the support team has enabled the Tracking feature for it
• The order carries status, currency, order_total, and items[] including product_title and quantity
• The order carries source_created_at
• The fulfillment trackings[] uses id, not tracking_number
• The fulfillment line_items[] match the order items[]
• After creating them, the shipment is visible in your Tracking dashboard
• If you plan to use Apple Wallet: the add-on is enabled and the Apple Wallet Order Page is configured