How to Unify Shipment Tracking across Australia and New Zealand with One API

To unify shipment tracking across Australia and New Zealand with one API, connect your order or fulfilment system to a multi-carrier tracking service, register each shipment with the correct carrier identity, and translate incoming tracking updates into a consistent internal event model. The integration should preserve carrier-specific details while giving your operations team and customers one tracking experience across domestic and trans-Tasman deliveries.

For developers, ecommerce operators, and logistics teams, the main challenge is not making the first API request. It is keeping shipment identities, delivery statuses, carrier handovers, and customer notifications consistent when different carriers describe the same journey differently. This guide explains how to design that integration, evaluate a tracking API, and test it before relying on it in production.

Define what the single API needs to unify

A shared API gives your application a common integration point. It does not make every carrier publish identical information or scan parcels at the same frequency. Your architecture needs to distinguish between a consistent interface and complete visibility.

Start with a shipment inventory based on actual fulfilment activity, rather than a general list of carriers operating in either country. Include domestic Australian shipments, domestic New Zealand shipments, and cross-border movements in both directions. Add other international origins if they form part of your business.

• Carrier and service: Record the carrier, service used, and any known delivery partner.
• Route: Distinguish the shipment's origin and destination from the location of its latest scan.
• Identifiers: Capture the order reference, fulfilment reference, tracking number, and any replacement or partner number.
• Operational purpose: Specify whether updates support customer tracking, exception management, delivery confirmation, or all three.
• Required detail: Decide whether a broad delivery status is sufficient or whether agents also need scan descriptions, locations, and timestamps.

This inventory becomes your acceptance checklist. A provider's general carrier coverage is useful for shortlisting, but your decision should rest on whether your actual carrier-service combinations return usable tracking information.

Evaluate the tracking API against your shipment mix

17TRACK offers a Tracking API, making it a relevant option to evaluate for a multi-carrier integration. Use its official API documentation to check the current integration requirements. Treat carrier support, event fields, update behaviour, account limits, and commercial terms as items to verify for your implementation, not assumptions derived from the product category.

Ask the same practical questions of any API you consider:

• Can it identify and track the carriers and services in your shipment inventory?
• When carrier detection is ambiguous, can you supply an explicit carrier identifier?
• How does your application receive updates, and what recovery mechanism is available if an update is missed?
• Which original carrier details remain available alongside normalised statuses?
• What happens when a tracking number is invalid, not yet recognised, or associated with more than one possible carrier?
• How are usage, billing, tracking duration, and access limits defined for your account?

Recommended decision rule: choose based on successful tests of your real shipping patterns, not the largest headline carrier count. An integration is suitable when it provides enough information to support your operating decisions and exposes failures clearly enough to recover from them.

Build an internal model that survives carrier differences

Separate orders, shipments, and tracking legs

Do not use the tracking number as the primary key for an order. One order can contain several parcels, and a parcel journey may involve more than one tracking identifier. Instead, create an internal shipment ID and attach tracking records to it.

A practical model has three levels: the customer order, its physical shipments, and the tracking legs associated with each shipment. A domestic parcel may need only one tracking leg. A cross-border parcel may require linked records when another carrier or identifier becomes relevant.

Scope a tracking record by carrier as well as tracking number, and retain its relationship to your shipment ID. If a new delivery-partner number appears, add it as a related identifier rather than overwriting the original. This preserves the history support agents need when investigating a handover.

Keep a raw event and a normalised event

Use a small internal status vocabulary that your business can act on. For example, you might define pre-transit, in transit, out for delivery, available for collection, delivered, exception, and unknown. These are suggested internal categories, not a claim about a particular provider's status schema.

Store the original carrier description alongside your mapped status. A collection-point event and an address problem could both require customer action, but they should not produce the same message. Likewise, creating a label should not automatically become evidence that the carrier physically holds the parcel.

Document mapping decisions in a versioned configuration. When a new event description appears, place it in a review queue if its meaning is unclear. An explicit unknown state is safer than confidently assigning the wrong delivery outcome.

Distinguish event time from receipt time

Store when an event occurred separately from when your system received it. An older scan can arrive after a newer one, particularly when updates are delayed or historical events are supplied together.

For Australia and New Zealand, avoid applying one fixed time offset to every shipment. Preserve source timestamps and offsets when supplied. Use an appropriate named time zone for display when you have reliable location context, and account for daylight-saving differences. If the source time zone is missing, retain that uncertainty rather than inventing a precise UTC conversion.

Implement a reliable ingestion workflow

1. Create the internal shipment first. Record its order relationship, route, carrier selection, and tracking identifier before registration with the tracking service.
2. Submit the tracking registration. Use the provider's documented request format. Store the response and distinguish successful registration from the later availability of carrier events.
3. Classify failures. Separate invalid input and authentication problems from temporary service failures. Retry only where retrying can reasonably help.
4. Receive or retrieve updates. Implement the delivery mechanism supported by your chosen API. If using webhooks, validate incoming requests using the provider's documented method and process accepted events through a durable queue.
5. Deduplicate before applying changes. Use a provider event identifier where available, or a carefully designed composite key. Repeated delivery must not trigger repeated customer notifications.
6. Recalculate shipment state. Evaluate event meaning and chronology instead of replacing the current status with whichever update arrived last.
7. Reconcile incomplete records. Where the API supports retrieval, use it to investigate missed updates or stale records within the applicable usage limits.

Keep provider-specific authentication, field names, and error handling inside an adapter. Your order management system should consume your internal shipment model rather than depend directly on every detail of a provider response. That separation also makes later API changes easier to test.

Handle trans-Tasman journeys without inventing certainty

Cross-border tracking needs more context than a sequence of status labels. Your application should distinguish an export event, a customs-related event, a carrier handover, and a final-delivery event when the source data supports those distinctions.

Do not infer customs clearance from a generic in-transit scan. Similarly, the absence of a recent scan does not establish that customs is holding the parcel. A useful customer message states the last confirmed event and its time, then explains any next action your team can actually support.

Keep origin and destination separate from scan location. A shipment travelling from Australia to New Zealand does not become a domestic New Zealand shipment simply because it has received an arrival scan. That distinction matters for route reporting and exception ownership.

If a delivery partner becomes involved, link its tracking record only when the relationship is supported by shipment data, the tracking service, or an operationally verified record. Do not merge parcels merely because identifiers look similar.

Turn tracking events into useful customer updates

Your customer-facing page should answer four questions: what is the latest confirmed status, when did it happen, where was it recorded if known, and does the customer need to act?

Keep notification rules separate from event ingestion. Not every scan deserves an email or text message. Define meaningful transitions, such as a first confirmed movement, delivery attempt, collection requirement, or delivered event, and suppress repeated alerts for the same transition.

• Stale tracking: State when the last update occurred without treating silence as proof of loss.
• Delivery estimates: Distinguish a carrier-provided estimate from a merchant promise. Do not manufacture a date when neither exists.
• Exceptions: Give a concrete next step where known, rather than displaying an unexplained error label.
• Delivered disputes: Preserve the source event and route the case to support; a delivered status alone does not resolve every customer dispute.

Protect tracking pages as well as API credentials. Avoid exposing unnecessary address or contact details, keep service credentials on the server, and apply access controls appropriate to the information displayed.

Run a route-based pilot before rollout

Test domestic Australian, domestic New Zealand, Australia-to-New Zealand, and New Zealand-to-Australia shipments where those routes are relevant to your business. Include ordinary deliveries and operational edge cases: split orders, unrecognised numbers, handovers, delivery attempts, collection events, returns, and late-arriving scans.

Use real shipment records with suitable permission for carrier validation. Use synthetic events to test your own application's resilience, but do not treat synthetic results as evidence of live carrier coverage.

• Identity check: Each update reaches the correct shipment and order.
• Chronology check: Out-of-order events do not incorrectly reverse delivery progress.
• Recovery check: Temporary failures and duplicate updates do not lose data or repeat alerts.
• Support check: Agents can inspect the original event and understand the customer-facing status.
• Commercial check: Expected usage fits the account's verified billing model and limits.

Set acceptance thresholds before evaluating the pilot. Measure registration outcomes, unmapped events, processing delays, notification duplicates, and unresolved stale shipments. Separate carrier-data delays from delays inside your own application so that remediation reaches the right owner.

The implementation is ready when your team can explain and recover from incomplete tracking, not merely display successful deliveries. One API simplifies connectivity; your shipment model, event rules, and operating procedures make that connectivity dependable.

FAQ

Does one tracking API replace carrier shipping integrations?

Not necessarily. Tracking, label creation, pickup booking, rate calculation, and customs documentation are separate functions. Verify the scope of the selected product and retain other integrations where your fulfilment process needs them.

Can I register a tracking number before the first carrier scan?

Check the API's registration rules. Design your application to distinguish an accepted tracking registration from confirmed physical movement. A record with no events should not automatically be shown as in transit.

Will a single API provide real-time updates for every carrier?

Do not assume that. End-to-end freshness depends on when the carrier publishes data, when the tracking service obtains it, and when your application processes it. Confirm update behaviour for the carrier-service combinations you use.

What should happen when the tracking number changes?

Retain the original identifier and attach the verified replacement or partner identifier to the same internal shipment. Preserve both histories, and prevent duplicate records from generating conflicting notifications.

Is 17TRACK relevant to this integration?

Yes. Its Tracking API is relevant to the multi-carrier integration described here. Evaluate it using your Australian and New Zealand shipment samples, and confirm carrier support, technical behaviour, and account terms through the official API resources before deployment.

Sources

• 17TRACK Tracking API — official product resource for the API option discussed in this guide.
• 17TRACK API documentation — official technical reference for checking request formats, integration requirements, and supported behaviour.