Order tracking API for multi-seller marketplaces

Model buyer order, seller fulfillment and parcel separately

Associate each parcel with your marketplace order and seller fulfillment in your application. Create distinct Trace records for split deliveries, replacement parcels and recycled-number cycles. Use namespaced order references and stable Idempotency-Key values so a retry does not create another record.

If multiple sellers share your Trace account, the account’s API key can access its account-owned records. Trace does not automatically isolate those sellers as your application tenants. Enforce seller and buyer authorization in your backend before returning tracking information or allowing metadata updates.

Use synchronous batches for small lookup groups

POST /v1/track/batch accepts up to 20 numbers. Its JSON body contains results, failed_count and request_id; it is not a top-level array. Mixed outcomes use HTTP 200, and an entirely failed batch uses HTTP 503 with its results array. Inspect each item instead of treating a 200 as universal success.

A batch reserves quota before work starts and charges successful items, including cache hits and explicitly allowed stale results. Failed items release their reservation. Upstream work is bounded, so a large synchronous batch can outlast a short application timeout. Use small batches or durable record imports when the request would otherwise block a buyer’s page.

const numbers = [process.env.PARCEL_A, process.env.PARCEL_B];
if (numbers.some(n => !n)) throw new Error('Set both real parcel numbers');
const response = await fetch('https://api.traceapi.dev/v1/track/batch', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TRACE_API_KEY}`,
    'Content-Type': 'application/json' },
  body: JSON.stringify({ tracking_numbers: numbers }),
  signal: AbortSignal.timeout(190000)
});
const body = await response.json();
if (!Array.isArray(body.results)) {
  throw new Error(body.error?.message || 'No batch results');
}
for (const result of body.results) {
  if (result.error) {
    console.warn('Parcel lookup unavailable', result.error.code);
    continue;
  }
  console.log(result.carrier.code, result.status, result.last_checked_at);
}
console.log('Failures:', body.failed_count, 'Request:', body.request_id);

Use durable imports for seller uploads and historical records

An async import creates order-linked shipment records from JSON rows or CSV. Supply a stable Idempotency-Key for the import, store the returned job ID, and poll its owned results to map each row to a shipment ID or validation error. The API accepts up to 1,000 rows per job, or CSV text up to 750 KB.

Import success means record creation. Carrier verification happens through acquisition and monitoring, so distinguish accepted seller uploads, created records and verified timelines in your admin UI. Cancellation stops remaining work and retains completed records; an operator should see those partial results rather than re-uploading the entire file blindly.

• Preserve row numbers and seller references when presenting validation errors.
• Restrict order references and metadata to the merchant fields your application needs.
• Use per-parcel records and the returned IDs rather than assuming the imported number uniquely identifies a lifecycle.
• Respect the unfinished-job and active-record limits documented for the account’s plan.

Build an order summary from evidence, not webhook arrival order

Verify shipment webhooks and deduplicate event IDs before updating your projection. Re-read the current owned shipment when an event would overwrite newer local evidence or when you need to reconcile a receiver outage. Do not assume webhook arrival order matches scan chronology.

Show the latest verified state and last check time for each parcel. A source outage should affect the freshness label, not silently convert an in-transit parcel to pending. For mixed timezone histories, preserve source-local labels and avoid inventing a globally sorted UTC timeline.

For example, an exception on one seller’s parcel can open a support action while another seller’s delivered parcel remains complete. A platform-wide refund or seller-performance penalty needs its own evidence and business policy; an inferred no-scan alert alone is not enough.

Choose rollout metrics that expose missing data

Measure verified records as a share of all imported records, by carrier and destination. Include unmatched or unavailable parcels in the denominator, otherwise the dashboard can look successful while difficult sellers are systematically excluded. Track the age of observations and the fraction of unknown-timezone scans.

Trace’s merchant analytics expose account-owned cohorts with UTC duration sample counts and excluded durations. Use that as a description of observed history rather than a causal carrier ranking. Qualify a seller/carrier cohort before expanding customer access, and maintain a support path for disputed delivery evidence.

• Use sandbox cases to verify partial-order presentation and error handling.
• Test buyer and seller authorization separately from Trace account authentication.
• Budget direct, cached, stale and successful monitoring lookups together.
• Validate retries and import continuation using saved results, not repeated full-file creation.

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 batch result and quota contract
• Trace durable import contract