Tracking API for cross-border dropshipping orders

Keep supplier identifiers separate from parcel identity

Link your storefront order, supplier reference and parcel number in your own system. Create a Trace shipment record with order_id and a parcel-cycle Idempotency-Key. You can retain a supplier label in metadata without sending that business context to the tracking source.

If a supplier provides a replacement or last-mile tracking number, preserve both references. A carrier code should describe the parcel you are actually querying. Do not overwrite the original number and present two different parcel histories as one continuous verified timeline.

Qualify the route instead of assuming universal coverage

Use the carrier supplied by the merchant or supplier when it maps to Trace’s catalog. Automatic detection handles selected formats; numeric or overlapping formats may need an override. A catalog entry does not demonstrate reliable retrieval for a particular route.

Test several authorized shipments for the same supplier and carrier, including newly labelled, in-transit and delivered parcels. Record whether a matching source timeline exists, whether timestamps have known offsets, and how often retrieval fails. A successful lookup for one parcel does not establish coverage for all of a supplier’s traffic.

const number = process.env.TRACKING_NUMBER;
if (!number) throw new Error('Set TRACKING_NUMBER');
const response = await fetch('https://api.traceapi.dev/v1/track', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TRACE_API_KEY}`,
    'Content-Type': 'application/json' },
  body: JSON.stringify({ tracking_number: number, carrier: 'yunexpress' }),
  signal: AbortSignal.timeout(95000)
});
const tracking = await response.json();
if (!response.ok) throw new Error(tracking.error?.message || 'Unavailable');
console.log(tracking.status, tracking.last_checked_at);

Preserve local scan times and incomplete histories

Some tracking pages omit timezone information. Trace can retain an event with timestamp: null, timestamp_local and timestamp_timezone: unknown. Display the original local time with its limitation. Do not add Z, guess the offset from a country, or sort mixed-zone events as if they were verified UTC instants.

Carrier history may also be incomplete. A normalized status helps your application organize a source’s report, but it is not independent proof of a customs release, acceptance or delivery. Keep the scan wording available to support staff and use the official carrier or supplier for disputed shipments.

For example, two scans both labelled 09:00 may have occurred in different places and timezones. A support agent should see their supplied history order and source-local labels rather than an apparently precise transit duration calculated from guesses.

Route exceptions to a human-readable next step

Carrier exception alerts and Trace no-scan alerts have different evidence. Carrier facts attribute the source’s exception. A Trace inference identifies an absence of recent scans under a defined rule; it requires a successful verified observation and UTC instants for every scan. Unknown timezones and failed or stale lookups do not establish a stall.

Build separate support actions for supplier follow-up, recipient-address checks and carrier redelivery instructions. A no-scan action should ask for investigation, not automatically tell the buyer that the parcel is lost. A customs scan should preserve the source wording rather than asking every customer for the same generic document.

Plan refreshes and evaluate merchant outcomes

Owned shipment records support best-effort monitoring for up to 30 days, with roughly six-hour intervals after a successful check and backoff on failures. Longer cross-border journeys may outlast the monitoring window, so your application needs a deliberate policy for follow-up and a new record cycle when appropriate.

Measure verified-result rate, unknown-timezone frequency, age of the last observation, support contacts per order and unresolved exceptions per supplier cohort. Use these measures to decide where Trace adds value. Do not promise a reduced dispute rate or supplier ranking without your own representative evidence.

• Make the page usable when a carrier returns no timeline or no estimate.
• Keep destination and supplier details minimal; do not place buyer email addresses or other unnecessary personal data in tracking requests.
• Count successful background refreshes in the same monthly lookup budget as direct requests.
• Run a canary cohort before routing all new orders to a newly qualified source.

Common questions

References & next steps

Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.

• Trace carrier catalog and detection scope
• Trace alert evidence and timezone rules