
Plenty of shops run on this routine: the courier updates the parcel status in its own dashboard, and someone on the team looks it up and types it into Shopify. This article is for the owner who wants that to stop and the technical person who will build the replacement. Shopify tracking number automation comes down to a scheduled job, a clean data model and careful handling of cash on delivery (COD) and returns.
Does Shopify update tracking automatically?
Partly. Shopify emails the customer when you fulfil an order with a tracking number, and labels bought through Shopify Shipping add the number for you. What Shopify does not do on its own is read your courier’s system and write the parcel’s progress back. Something has to fetch that status: a tracking app, an aggregator service, or your own job. The rest of this article is about that last piece.
The life of one order
Paid or placed, then fulfilled, then a tracking number goes onto the fulfilment. After that the courier generates events: booked, picked up, in transit, out for delivery, attempted, delivered, or returned. Your automation turns those events into Shopify updates, and for COD it marks the order paid on delivery. Steps one to three are usually fine already. The gap is everything after the number is attached.
How tracking numbers reach a Shopify fulfilment
Staff can type them into the admin, a shipping app can add them when it books the parcel, or your system can use the Admin API. Three mutations matter, all documented on shopify.dev:
fulfillmentCreatefulfils one or more fulfilment orders. It needs one of the fulfilment-order write scopes plus the staff permission to fulfil and ship.fulfillmentTrackingInfoUpdatechanges the carrier, number and URL on an existing fulfilment. It takes several numbers for multi-parcel shipments, and an optionalnotifyCustomerflag. Leave the flag out and nobody is emailed.fulfillmentEventCreaterecords a status event such as in transit or delivered. It needswrite_fulfillments.
Check each against the API version you target. The custom app build guide covers scopes and tokens.
What to store
Keep the data model small enough to explain on one page.
| Field | Why you need it |
|---|---|
Shopify order ID and order name (#1042) | To match courier records to orders |
| Fulfilment ID | Events and tracking updates attach to it |
| Courier code | Picks the right adapter |
| Tracking number | The key you ask the courier about |
| Last courier status and time | To spot a real change |
| Last status already sent to Shopify | Stops duplicate events |
| Next check time, and a done flag | Drives the schedule |
The courier and number live on the Shopify fulfilment. Copying them to an order metafield helps staff, Flow and reports see them (see the metafields guide). The polling state belongs in your own database.
Polling, courier webhooks or an aggregator
| Approach | How it works | Strength | Weakness |
|---|---|---|---|
| Polling | Your job asks each courier’s tracking API about each open parcel | Works with any courier that has an API | Rate limits, wasted calls |
| Courier webhook | Courier calls you on a status change | Quick, fewer calls | Few couriers offer it; keep a fallback |
| Aggregator API | One service tracks many couriers | One integration | Fees, uneven coverage, another party holds the data |
Public documentation varies wildly. DHL publishes a shipment tracking API with an API key, and its starting access level is limited to 250 calls a day and one call every five seconds, so production use means asking for an upgrade. For couriers common in Pakistan and South Asia, such as PostEx, TCS, Leopards, M&P, Trax and Pakistan Post, I could not find complete public developer documentation, and merchant API access seems to come through the courier’s account or integration team. Ask each one for its official API documentation and your own credentials, and do not guess endpoints.
Designing the polling job
Poll only fulfilled orders that have a tracking number and are not marked done. Start with a check every few hours and tighten it only when the business needs it: parcels out for delivery deserve a closer look than ones booked this morning. Stay under each courier’s documented rate limit with a per-courier budget. If a courier takes several tracking numbers per request, batch them. On errors or a 429 response, wait and retry with growing delays rather than hammering. Stop when the parcel reaches a final status, or after a maximum idle period, at which point a human gets a flag.
Mapping courier statuses to Shopify
Couriers each have their own words, so translate them into a small internal set first. Shopify’s FulfillmentEventStatus lists these values: LABEL_PURCHASED, LABEL_PRINTED, READY_FOR_PICKUP, CONFIRMED, CARRIER_PICKED_UP, IN_TRANSIT, OUT_FOR_DELIVERY, ATTEMPTED_DELIVERY, DELAYED, DELIVERED and FAILURE.
| Typical courier status | Shopify event | Order action |
|---|---|---|
| Booked, label created | CONFIRMED or LABEL_PURCHASED | None |
| Picked up | CARRIER_PICKED_UP | None |
| In transit, at hub | IN_TRANSIT | None |
| Out for delivery | OUT_FOR_DELIVERY | Optional customer message |
| Attempted, failed | ATTEMPTED_DELIVERY | Staff contact the customer |
| Delayed, on hold | DELAYED | Staff flag |
| Delivered | DELIVERED | COD: mark paid; stop polling |
| Returned to sender | FAILURE plus a tag | Staff review |
Put the courier’s raw wording in your log and a short, plain message in the event’s message field.
Cash on delivery and returned parcels
With COD the order starts unpaid, the courier collects cash, and the money reaches you later. On a delivered status, call orderMarkAsPaid. Shopify designed it for payments received outside checkout, including COD. It needs write_orders and the mark-as-paid permission, and returns an error if the order is already paid. Delivered is not the same as banked, so reconcile against the courier’s remittance report separately.
Refused and returned parcels (return to origin, or RTO) are where I would keep a person in the loop. Tag the order, add a note and alert staff. orderCancel can cancel and restock, but it is irreversible and runs as an asynchronous job, and for a parcel that already shipped, a returns process that restocks when the item physically arrives is usually the safer path.
Keeping customers informed
Use the tracking mutation when the number or carrier changes, and the event mutation for each real status change. Decide which events customers hear about. Shipped, out for delivery, delivered and problems are plenty; a message for every scan trains people to ignore you. Shopify’s order status page reads from the fulfilment, so correct tracking data there keeps it honest. Wording can be changed through order notification emails and SMS. If you send email or SMS, collect consent and follow local law (GDPR, ePrivacy, CCPA and similar). This is not legal advice.
Edge cases that bite
- Split shipments. Each fulfilment has its own tracking number, so track per fulfilment, not per order.
- Several parcels, one shipment. The tracking input accepts multiple numbers.
- Lost parcels. No movement for a set number of days should raise an alert, never an automatic refund.
- Rerouted parcels. Record the new number on the fulfilment.
- Bad numbers. Check the format per courier before polling.
Architecture
Scheduler -> due shipments -> queue
Worker -> courier adapter (one per courier) -> normalised status
Changed? -> Shopify client (event, tracking, mark paid) -> audit log
Failures -> retry with backoff -> alert a named person
Each courier gets its own adapter that returns your internal statuses, so adding a courier means writing one adapter and touching nothing else. Before sending an event, compare against “last status sent” so the same one never goes twice. Keep an audit log with the raw courier response, the mapped status, Shopify’s reply and the time, because you will want it the first time a customer disputes a delivery.
Example timeline for one order
This is an illustrative example, not a real order.
| When | What happens | System action |
|---|---|---|
| Day 0, morning | Order #1042 placed, COD | Order unpaid |
| Day 0, afternoon | Staff fulfil; booking returns a tracking number | Saved on fulfilment and metafield |
| Day 1 | Courier: picked up | CARRIER_PICKED_UP event |
| Day 2 | Courier: in transit | IN_TRANSIT event |
| Day 3, morning | Courier: out for delivery | OUT_FOR_DELIVERY, optional customer message |
| Day 3, afternoon | Courier: delivered | DELIVERED event, order marked paid, polling stops |
| Next poll | Same status again | Ignored |
Build or buy
| Aggregator app (AfterShip, ParcelPanel, 17TRACK, TrackingMore and similar) | Custom app with adapters | |
|---|---|---|
| Setup | Short | Longer |
| Coverage | Wide lists; check your couriers | Any courier with an API, one adapter each |
| COD and RTO rules | What the app offers | Exactly yours |
| Cost | Subscription, often by volume | Build, hosting and upkeep |
| Data | Shared with the vendor | Stays with you |
| Maintenance | Vendor | You or your agency |
If an app already covers your couriers and your rules are ordinary, buy it. If your couriers are local ones the aggregators do not cover, or your COD and return rules are specific, a custom app is reasonable.
Frequently Asked Questions
Can Shopify pull tracking updates from my courier without an app?
No. Shopify stores and shows tracking numbers, but a shipping app, aggregator or custom job has to read the courier’s status and write it back.
How often should I check the courier?
Every few hours to begin with, more often for parcels near delivery. Stay inside the courier’s documented limits.
Should every scan send an email?
No. Send on shipped, out for delivery, delivered and problems. More than that raises opt-outs.
Can the job cancel returned COD orders?
It can, but flag them for staff first. Cancelling is irreversible and the right move depends on whether the goods are back on your shelf.
Will a custom app work with my local postal service?
If that service offers merchants a tracking API or data feed, yes, with one adapter. Get its official documentation and credentials.
If your couriers are Pakistani, our guide to Shopify courier integration in Pakistan, apps vs custom covers the same decision with local couriers in mind. For a worked example with an international courier, see the Shopify DHL tracking setup and automation guide.
Conclusion
Shopify tracking number automation is a data-matching job: order ID, courier, tracking number, status. A scheduled job with one adapter per courier removes the copy-and-paste work and keeps customers informed, as long as COD and returns keep a human checkpoint until you trust the data. If you would like help with this, CYPHEX can plan and deliver it for you, with one project lead as your contact. See also our Shopify services and automation work.
Stock photography provided by Pexels under the Pexels License.
