Trace docs

Authentication

Every request goes to the same base URL. Send your API key as a Bearer token and keep live keys on your server, never in public frontend code.

https://api.traceapi.dev

Authorization: Bearer trc_live_xxxxxxxxxxxxx

Track one shipment. Trace detects the likely carrier, fetches current tracking data, normalizes status, and returns carrier events when available.

{ "tracking_number": "YT2412345678" }

{
  "tracking_number": "YT2412345678",
  "carrier": {
    "code": "yunexpress",
    "name": "YunExpress",
    "type": "dropshipping"
  },
  "status": "in_transit",
  "estimated_delivery": null,
  "events": [
    {
      "status": "in_transit",
      "description": "Departed origin facility",
      "location": "Shenzhen, China",
      "timestamp": "2026-07-03T09:30:00.000Z"
    }
  ],
  "cached": false,
  "request_id": "req_abc123",
  "last_checked_at": "2026-07-03T10:00:00.000Z"
}

Response fields

Every tracking response uses the same shape, whether the lookup is fresh, served from cache, or the carrier has no new scans yet.

pending           Label created; the carrier has not received the package yet.
in_transit        Package is moving through the carrier network.
out_for_delivery  On the vehicle for final delivery.
customs           Held in customs or clearance.
delivered         Delivered.
exception         Delivery problem: failed attempt, held, returned, or customs delay.

Track up to 20 shipments in one request. Batch calls count each tracking number toward usage.

{
  "tracking_numbers": [
    "YT2412345678",
    "1Z999AA10123456784"
  ]
}

Carrier codes

The carrier.code values returned by the API, with the tracking number prefixes used for auto-detection. Unrecognized numbers return unknown and Trace still attempts a lookup.

Carriers shown as Numeric use purely numeric tracking numbers with no alphabetic prefix, so they are matched by length and digit patterns rather than a prefix string.

Webhooks

Add an endpoint in the dashboard and Trace will POST signed tracking events to your app. You can test delivery from the Webhooks page before using it in production.

tracking.updated
tracking.delivered
tracking.exception

{
  "event_id": "evt_abc123",
  "event_type": "tracking.updated",
  "created_at": "2026-07-03T10:00:00.000Z",
  "tracking": {
    "tracking_number": "YT2412345678",
    "status": "in_transit",
    "carrier": {
      "code": "yunexpress",
      "name": "YunExpress"
    },
    "events": []
  }
}

Trace-Event: tracking.updated
Trace-Timestamp: 1783072800
Trace-Signature: t=1783072800,v1=signature_hash

import crypto from "node:crypto";

const expected = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${req.headers["trace-timestamp"]}.${rawBody}`)
  .digest("hex");

const trusted = req.headers["trace-signature"]?.includes(`v1=${expected}`);

Tracking playground

Test a live tracking request from the docs. Your key is sent only to the Trace API.

Client snippets

Copy-paste clients for your stack — no dependencies, same request shape the official Trace SDKs wrap.

export async function trackPackage(apiKey, trackingNumber) {
  const response = await fetch("https://api.traceapi.dev/v1/track", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ tracking_number: trackingNumber })
  });

  if (!response.ok) throw new Error("Trace request failed");
  return response.json();
}

import requests

def track_package(api_key, tracking_number):
    response = requests.post(
        "https://api.traceapi.dev/v1/track",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"tracking_number": tracking_number},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Limits and quotas

Errors

Every error returns the same shape: { "error": { "code", "message" } } with one of the codes below.

Health check

{ "ok": true, "service": "trace-api" }