Customers do not think in carrier portals. They want to open an order page, see where a package is, and understand what happens next. A Shopify store can provide that experience by connecting fulfillment tracking numbers to a multi-carrier package tracking API.
This guide explains the integration decisions that matter: where to capture tracking numbers, how often to request updates, how to normalize carrier statuses, and how to handle delivery exceptions. It assumes the API key stays on your server—not in a theme or browser script.
1. Decide what the customer should see
Start with the experience, not the endpoint. A useful Shopify tracking page usually includes the order number, carrier, tracking number, latest status, last update time, estimated delivery when available, and a link to the carrier’s official page.
Keep the customer-facing language simpler than the raw carrier message. “In transit” is easier to understand than a carrier-specific scan description. Preserve the original event internally for support and auditing.
2. Capture tracking data from Shopify
When an order is fulfilled, store the fulfillment’s tracking number and carrier name in your application database. Do not rely on a product SKU or Shopify order number as the carrier identifier. One order may have multiple fulfillments, split shipments, or more than one tracking number.
Store at minimum: Shopify order ID, fulfillment ID, tracking number, carrier, destination country, API status, last checked time, latest event, and delivered-at time.
If your store uses a fulfillment service or 3PL, confirm when the tracking number becomes available and whether it can change after a carrier handoff.
3. Keep the API key on your server
Your Shopify theme, storefront JavaScript, and customer browser should never contain the tracking API key. Use a server-side app, backend route, or integration service to call the API, then return only the tracking data your storefront needs.
Use environment-specific secrets, restrict administrative access, log request IDs rather than credentials, and redact tracking data from general-purpose logs where appropriate.
4. Choose polling that fits the shipment lifecycle
For a request-based API, polling is the mechanism that discovers new carrier events. Do not check every package at the same interval forever. A practical schedule can be slower immediately after label creation, more frequent while a package is moving, and stopped after delivery or a final cancellation state.
Example policy: check new labels once daily until the first scan, active shipments two to four times daily, and exception shipments more often only when your operations team needs faster visibility.
Use backoff after timeouts and HTTP 429 responses. Add jitter so thousands of shipments do not all run at the same second. For a request-budget example, see How to Estimate Package Tracking API Costs.
5. Normalize carrier statuses
Carrier status strings vary widely. Map them into a small internal model that your Shopify tracking page and notifications can use consistently:
- Label created: the number exists but the carrier has not recorded movement.
- In transit: the package is moving through the network.
- Out for delivery: the final delivery attempt is expected soon.
- Delivered: the carrier reports completion.
- Exception: a delay, address issue, customs event, failed attempt, or other action may need attention.
- Unknown: the API or carrier has not supplied enough information to classify the shipment.
Keep the raw event and timestamp alongside your normalized status. That makes it possible to improve your mapping without losing the original evidence.
6. Design for exceptions, not only successful deliveries
A tracking page that only celebrates “delivered” is incomplete. Decide what the store should do when a package is delayed, held at customs, returned, marked as undeliverable, or has not received its first scan.
For high-impact exceptions, create an internal task or notification rather than sending every raw carrier event to the customer. Your customer-support team can then contact the buyer with useful context. See How to Detect Delivery Exceptions Automatically for a deeper workflow.
7. Build a simple tracking page
A Shopify tracking page can be a route in a custom app, a customer-account extension, or a branded page that receives an order-specific token. Avoid exposing a tracking number as the only authorization mechanism; combine it with an order token or authenticated customer session.
Show the latest status first, then a chronological timeline. Include a “last updated” timestamp and explain that carrier scans are not continuous. Make the page mobile-friendly because many post-purchase visits happen on phones.
8. Plan for multiple carriers and split shipments
Do not hard-code a single carrier’s response shape into your order model. A Shopify order can contain multiple tracking numbers from different carriers, and an international shipment may change carriers during its journey.
Render one shipment card per tracking number, then summarize the order separately. This avoids hiding a delayed item behind a delivered item from the same order.
9. Test before sending customer notifications
Use representative tracking numbers from every carrier you expect to support. Test label-created, in-transit, delivered, delayed, exception, invalid, and no-data responses. Also test duplicate events, out-of-order timestamps, API timeouts, and a tracking number that changes after handoff.
Run a short pilot and measure requests per active shipment, average monitoring duration, retry rate, and peak daily usage. Compare that workload with the current C2W request budgets before launch.
10. A practical launch checklist
- Capture tracking numbers from every fulfillment, including split shipments.
- Keep API credentials server-side.
- Store raw events and normalized statuses.
- Use adaptive polling with backoff and jitter.
- Stop monitoring delivered and terminal shipments.
- Define customer and internal responses for exceptions.
- Test carrier-specific and multi-carrier scenarios.
- Monitor request volume and rate limits after launch.
Frequently asked questions
Can I call a tracking API directly from my Shopify theme?
Do not expose the API key in theme JavaScript. Put the API call behind a server-side app or protected backend route.
Does one Shopify order equal one tracking request?
No. An order may have multiple fulfillments, and a request-based provider may count every scheduled check separately. Model shipments and checks, not just orders.
Should I show every carrier event to customers?
Usually no. Normalize events into clear milestones and retain the raw carrier message for support and troubleshooting.