What Data Should a Tracking API Return? 12 Fields Beyond the Current Status?
A tracking API should return more than a label such as “In transit.” Beyond the current status, look for shipment identifiers, carrier identity, detailed status information, original carrier messages, event history, event timestamps, locations, delivery estimates, exceptions, carrier handoffs, delivery details, and data-freshness metadata. Together, these 12 data groups help developers build reliable workflows and give operations teams enough context to act.

This is a recommended response contract for developers, technical buyers, and ecommerce operations teams—not a claim that every carrier or API supplies every field. Some values will legitimately be unavailable. The better design makes those gaps explicit rather than filling them with assumptions.
What makes tracking data useful?
A current status answers one narrow question: what is the shipment’s summarized state? It does not necessarily explain what happened, when it happened, whether the information is recent, or what someone should do next.
For example, two shipments can both show “In transit” while requiring different responses. One may have a recent facility scan and no reported problem. Another may have an unresolved address issue recorded in its event history. An application that reads only the headline status can miss that distinction.
Evaluate the response against three practical tasks: matching the shipment to the correct order, explaining its progress accurately, and deciding whether an action is justified. The following fields support those tasks. Field names are illustrative; they are not a universal standard or a specific provider’s schema.
12 fields to evaluate beyond the current status
1. Shipment and tracking identifiers
The response should identify the shipment being described. Useful values include the submitted tracking number, the API’s tracking-record identifier, and a client reference that your system can map to a fulfillment or package record.
Do not assume one order equals one shipment. An order can be split across packages, and a replacement can create another shipment. Store tracking records at the package or fulfillment level, then associate them with the order. Preserve tracking numbers as strings so that formatting and leading zeros are not lost.
2. Carrier identity
Look for a stable carrier identifier alongside a readable carrier name. Where available, the response should distinguish a carrier explicitly supplied by your application from one selected through automatic detection.
Carrier context matters when interpreting a tracking number and its events. If detection is ambiguous, your integration should have a way to resolve it rather than silently presenting an uncertain match as confirmed. Keep service-level information separate: a carrier name alone does not establish whether a shipment uses an express, postal, or other service.
3. Normalized status detail
Alongside the main status, request a documented detail code or substatus. A broad category might describe a shipment as an exception, while the detail identifies an attempted delivery, an address problem, or a customs-related hold.
Use stable codes for business logic and readable labels for presentation. Confirm how the provider maps carrier events into those codes, including how it handles unknown or unmapped events. A normalized label makes different carrier feeds easier to consume, but it should not erase distinctions your support team needs.
4. Original carrier messages and codes
Retain the original event description and carrier event code when supplied. These values give support agents context that may be absent from a normalized status, especially when a carrier uses a specific operational phrase.
Keep original text separate from translated or rewritten descriptions. Otherwise, a customer-facing explanation can be mistaken for the carrier’s exact wording. Treat carrier text as untrusted input when displaying it: escape it appropriately and do not render it as executable HTML.
5. Tracking event history
A useful response should expose the shipment timeline, not just its latest event. Each event should ideally include an identifier, status or code, description, timestamp, and available location information.
Check whether the API returns the complete history, a limited window, or paginated results. Also establish how corrections and duplicate observations are represented. Your application should not assume the first item is always the newest unless the response contract explicitly guarantees that ordering.
6. Event timestamps and time-zone information
An event’s occurrence time is different from the time the API received or returned it. Preserve both when available. That distinction helps explain why a newly received update can describe something that happened earlier.
Request timestamps with explicit UTC offsets or UTC notation. RFC 3339 defines a timestamp format suitable for Internet protocols, including numeric time offsets. If a source supplies only local time without a known offset, preserve that uncertainty rather than silently treating it as UTC. Never imply second-level precision when the underlying source provides only a date.
7. Event locations and shipment geography
Look for structured location components such as city, region, country, and postal code when supplied. Preserve a raw location string as well if converting it into structured fields could lose meaning.
A scan location is not necessarily the package’s live position. Likewise, the last reported facility is not proof that the parcel remains there. Customer-facing pages should describe it as the latest reported location. Avoid inferring coordinates or an exact delivery address from incomplete scan text.
8. Estimated delivery date or window
An estimated delivery field should identify whether it contains a single date or a window, who produced it, and when it was last updated. A carrier-provided estimate and a separately calculated prediction should remain distinguishable.
Do not convert a date-only estimate into a precise arrival time. Your integration should also handle revised or withdrawn estimates without retaining an outdated promise on the tracking page. If no estimate exists, show that it is unavailable rather than calculating one from an unsupported assumption.
9. Exception reason and required action
Exception information should explain the issue and, where supported by the source, identify an action, responsible party, or deadline. A general delay notice is operationally different from a request for recipient information.
Keep reported facts separate from your own workflow decisions. For example, your business might open a support task after a configured period without an update. That is an internal escalation rule, not evidence that the carrier has declared the parcel lost. Do not generate payment instructions or sensitive information requests from ambiguous tracking text.
10. Carrier handoffs and related tracking numbers
Where a shipment moves between operators, useful data includes the next carrier, an associated tracking number, and the relationship between the original and downstream records. This can help preserve continuity when the delivery leg uses a different identifier.
Treat a reported handoff as a relationship rather than overwriting the original carrier. Do not merge records merely because their destinations or tracking numbers look similar. If the relationship is not supplied or otherwise confirmed, keep it unresolved instead of inventing a continuous journey.
11. Delivery outcome and proof references
When delivery is reported, the response should provide the recorded delivery time and any available delivery detail, such as a safe-place description or recipient category. A proof-of-delivery reference may also be useful where the carrier and service make it available.
A delivered status should not be treated as proof that the intended recipient personally accepted the parcel. Signatures, photographs, names, and precise locations may contain personal information. Limit access, avoid exposing these details on public tracking pages, and confirm any authorization or expiry requirements for proof links.
12. Freshness, retrieval state, and response metadata
Request enough metadata to distinguish the latest shipment event from the latest successful data retrieval. Useful values include the last successful check, last failed attempt, response-generation time, and whether returned data is cached or partial.
A successful API request does not, by itself, establish that the carrier has published a new scan. HTTP response semantics describe the request outcome; shipment progress belongs in the application data. Preserve retrieval errors separately from shipment exceptions so that a temporary connection problem does not become a false delivery alert.
Missing data needs a defined meaning
Field presence is only part of the contract. Your team also needs to understand what an absent value means. A delivery estimate might be unavailable from the source, not yet retrieved, or inapplicable after delivery. Those situations should not automatically produce the same customer message.
- Unknown: The value has not been established.
- Not supplied: The source did not provide the value in the retrieved data.
- Not applicable: The field does not apply to this record or state.
- Retrieval failed: The system could not complete the relevant lookup.
These are recommended distinctions, not mandatory literal values. Whatever representation you choose, document it. Avoid placeholder dates, empty objects that resemble valid records, and default coordinates that could be mistaken for real locations.
How to test the response before integrating it
Evaluate actual payloads from the carriers, services, and shipping routes your business uses. A schema can list an optional field without guaranteeing that every underlying source populates it. For a 17TRACK integration, use the official Tracking API documentation to check the response contract rather than treating the conceptual field names in this guide as copy-ready parameters.
- Build a representative sample. Include newly registered shipments, active shipments, delivery attempts, completed deliveries, and available handoff cases.
- Trace fields back to events. Confirm that the displayed status, latest event, and delivery details describe a consistent record. Investigate discrepancies instead of hiding them.
- Test delayed and repeated updates. Reprocess the same payload and receive an older event after a newer one. Confirm that neither case creates duplicate notifications or incorrectly reverses the displayed state.
- Test missing and malformed values. Include absent estimates, unknown locations, unfamiliar status codes, and incomplete timestamps. The application should remain usable without inventing replacements.
- Separate transport failures from tracking results. An authentication failure, timeout, or malformed response should enter an integration error path, not a shipment exception workflow.
- Validate the customer view. Check that internal references, raw diagnostic details, and personal information do not leak into public pages or notifications.
For webhook-based updates, also check delivery identifiers, authentication, retry behavior, and replay handling in the provider’s documentation. These are integration requirements rather than shipment facts. Your receiver should process repeated deliveries safely and should not assume arrival order equals event order.
The acceptance criterion should be practical: can your application explain the shipment without making unsupported claims, and can your operations team identify the next justified action? A smaller, well-defined payload can be more useful than a larger response full of unexplained optional values.
FAQ
Does every shipment need all 12 data groups populated?
No. Delivery evidence, downstream tracking numbers, and estimated delivery dates may not be available or applicable. Require clear field definitions and predictable missing-value behavior rather than universal population. Check the fields that matter most against your actual shipping mix.
Should we store the raw response or only normalized fields?
Store normalized fields for application logic. Retaining relevant source payloads can also help with debugging and mapping changes, subject to your privacy, security, contractual, and retention requirements. Restrict access and avoid retaining sensitive content simply because it appears in a response.
Which timestamp should determine the latest event?
Use documented event chronology and provider ordering rules, accounting for time zones and corrections. Receipt time tells you when your system learned about an event, not necessarily when it occurred. If timestamps are incomplete or conflicting, preserve the ambiguity instead of claiming a precise sequence.
Can a tracking API confirm that a package is lost?
Only treat a loss as carrier-reported when the source explicitly supports that interpretation. A long period without scans can justify investigation under your operational rules, but silence alone does not establish loss. Keep “stale tracking” and “reported lost” as separate concepts.
Is a delivered status enough to close a customer complaint?
Not automatically. It establishes the reported tracking outcome, but it may not resolve a recipient’s dispute. Review available delivery details, the customer’s account, and your support process. Avoid treating a status label as a substitute for investigating conflicting information.
Sources
- 17TRACK Tracking API documentation — the product-specific reference for checking an integration’s documented fields and behavior; the 12 groups above are editorial recommendations, not a reproduction of its schema.
- RFC 3339: Date and Time on the Internet: Timestamps — timestamp representation and time-offset conventions.
- RFC 9110: HTTP Semantics — HTTP response semantics, distinct from shipment-level business status.


