Executive summary
- What: the orderCreate mutation now accepts a trackingNumbers array on OrderCreateFulfillmentInput, available from API version 2026-10.
- Why: orders that ship in more than one package can be imported complete, with no follow-up mutation to attach the remaining numbers.
- Who: teams running ERP, OMS, or 3PL order imports, and anyone migrating historical order data onto Shopify Plus.
What changed
Until now, OrderCreateFulfillmentInput carried a single trackingNumber string. If a fulfillment shipped in three boxes, you created the order with one number and then issued a second call to attach the rest. The new trackingNumbers field takes an array of strings, so all of them land in the same write.
Two behaviours are worth understanding before you refactor. The trackingCompany value you supply applies to every number in the array, so a shipment split across two carriers still needs two fulfillments. And if you send both trackingNumber and trackingNumbers, the singular field takes precedence and the array is ignored. That rule exists so current integrations keep working untouched, but it also means a half-finished migration that leaves the old assignment in place will silently discard your new array.
The field is available starting in API version 2026-10. On 2026-07 and earlier, OrderCreateFulfillmentInput still exposes the singular field only.
Why it matters
The gain here is not a new capability, it is fewer moving parts. A two-call import is two opportunities to fail, two entries against your rate limit budget, and a window in which an order exists in Shopify in an incomplete state. At import volume that window is where reconciliation problems begin: shipping notifications that go out listing one tracking number instead of four, support agents looking at an order that does not match what the warehouse sent, analytics jobs that happen to read the order between the two writes.
Collapsing this into one mutation also simplifies error handling. Either the order is created with its full tracking picture or it is not created at all. Retry logic no longer has to distinguish between the order failing and the tracking patch failing, and the second of those is by far the more awkward state to recover from. If you are moving significant order volume through an integration, the same principles we cover in handling high volume orders and large catalogs apply directly here.
Role-specific impact
- Marketers: shipping notifications and post-purchase flows read complete tracking data on the first pass, so a customer receives one accurate message rather than a correction. Order status pages show every parcel from the moment the order lands.
- Developers: one less mutation in the import path and one less retry branch. Audit every place your code sets trackingNumber and replace it rather than adding alongside it, since leaving it populated will suppress the array.
- Store admins: imported multi-parcel orders look correct in admin immediately. Expect less manual patching of tracking on orders that arrived from an external system.
Use-case example
Real-world scenario
A furniture retailer imports roughly 4,000 orders a month from its ERP, after the goods have already shipped. Around 18 percent of those ship in more than one carton, which meant about 720 follow-up mutations every month whose only job was attaching the extra tracking numbers. Moving the import service to 2026-10 and passing trackingNumbers removes those calls outright.
The operational win is larger than the API saving. That same 18 percent of orders no longer sits briefly with partial tracking, which had been producing a steady trickle of tickets from customers who received the first notification, saw one number, and assumed a single box was the whole shipment.
Implementation checklist
- Confirm which API version your import service pins. The field does not exist before 2026-10.
- Audit every location where your code populates trackingNumber on OrderCreateFulfillmentInput.
- Replace the singular field with trackingNumbers rather than setting both, because the singular value wins and will hide the array.
- Group parcels by carrier before building the input, since trackingCompany applies to the entire array.
- Test with a genuine multi-parcel order and verify the confirmation email, the order status page, and the admin fulfillment card.
- Remove the follow-up tracking update call and its retry handling once the new path is confirmed.
- Watch your first production import for orders where tracking came through with a single number, which usually means a stale trackingNumber assignment survived the refactor.
FAQ
Q: Do we need to upgrade to 2026-10 to keep importing orders?
A: No. Integrations on earlier versions continue to behave exactly as they do today. The upgrade is only required if you want the array.
Q: Can each parcel in the array use a different carrier?
A: Not within one fulfillment. The trackingCompany value applies to every number you pass, so split mixed-carrier shipments into separate fulfillments.
Resources
orderCreate mutation reference
Need guidance? Talk to Makro.