A tracking number format can suggest a carrier, but it is not always unique. Numeric formats in particular may overlap. When your fulfillment system already knows the carrier, pass that evidence instead of making the API infer it again.
Trace accepts a catalog of 80+ carrier codes and recognizes selected tracking formats. Acceptance of a code does not mean that every number under that carrier currently returns live data. Keep identification and source qualification as separate checks.
Map fulfillment carrier names to accepted codes
Read the current carrier catalog and maintain an explicit mapping from your platform’s carrier identifiers to Trace codes. Preserve the original fulfillment value for support. Do not mechanically lowercase a display label and assume it is a valid API code; names, punctuation and aliases can differ.
Prefer an explicit mapping owned by your integration. If the mapping is unknown, either use supported automatic detection or ask the operator to correct the fulfillment record. Do not cycle through all carrier codes until a vaguely similar timeline appears.
Send the known code with the number
The carrier field is an override for the lookup. The number below is a placeholder and must be replaced with an authorized real shipment. A successful result still needs to correspond to the requested parcel, not merely contain plausible events.
cURL · use fulfillment evidence
curl https://api.traceapi.dev/v1/track \
-H "Authorization: Bearer $TRACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tracking_number":"YOUR_NUMBER","carrier":"ups"}'Do not turn ambiguity into a confident status
For numeric FedEx and DHL numbers, source evidence or a known carrier override can matter more than the string’s shape. A rejected or unavailable lookup should remain unavailable. It is safer to show an honest unresolved state than to attach another parcel’s movement to an order.
International handoffs can also introduce another tracking reference. Store the relationship in your fulfillment model when the supplier provides it; do not silently replace the outbound identity with a guessed last-mile number.
Qualify the carriers your store actually uses
Choose recent authorized samples with known scans and test each supported workflow: direct lookup, stored record and the UI projection. Record source availability separately from identification success. Include an unavailable result in your acceptance criteria so the application has an honest fallback when a source stops responding.
| Check | Evidence needed |
|---|---|
| Code accepted | Current catalog entry and valid request. |
| Carrier identified | Known fulfillment mapping or supported detection evidence. |
| Live acquisition works | Usable events for an authorized real number. |
| Integration is resilient | Correct timeout, unavailable and stale-data behavior. |
Common questions
Will providing a carrier code force a successful lookup?
No. It helps identify the intended carrier, but cannot create source data or bypass source unavailability.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.