Trackers

Track labels generated outside SendIt with normalized statuses and webhooks, whatever the carrier.

Trackers give you tracking for labels not generated through SendIt. Register any supported carrier’s tracking number. You get the same normalized statuses, event history, and webhooks as a SendIt shipment.

Labels purchased through SendIt are tracked automatically and free of charge. Trackers are only for external numbers.

Endpoints

List filters: search (partial tracking-number match), status, carrier, origin, isFinalized, createdAfter, and createdBefore. It also accepts livemode and is paginated.

isFinalized accepts true or false. Send isFinalized=false to list only the trackers still being polled.

Register an external number

Body parameters

curl -X POST https://api.sendit.mx/v1/trackers \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1234567890123456",
    "carrier": "DHL",
    "metadata": { "orderId": "ORD-2026-001" }
  }'

{
  "success": true,
  "data": {
    "id": "trk_a1b2c3d4e5f6",
    "trackingNumber": "1234567890123456",
    "carrier": "DHL",
    "status": "UNKNOWN",
    "events": [],
    "metadata": { "orderId": "ORD-2026-001" },
    "createdAt": "2026-07-18T10:00:00.000Z"
  }
}

• carrier is optional. SendIt infers it only when the number format identifies one carrier unambiguously. If the format is ambiguous, you receive 400 INVALID_INPUT: send the request again with a carrier hint.
• An unsupported carrier returns 422 CARRIER_NOT_SUPPORTED; one that needs account credentials returns 422 CARRIER_CREDENTIALS_REQUIRED until you configure that integration.
• The response arrives with status: "UNKNOWN" and an empty events array. The first carrier poll happens within about a minute. From then on, every status change fires a tracker.updated webhook.
• metadata is returned as-is, never interpreted.

Duplicates are free

Registering a number that already has an active tracker in your organization returns the existing tracker with meta.deduplicated: true, and is never charged again. This applies to the same number and carrier within the last 3 months. Client-side retries are always safe: this endpoint needs no Idempotency-Key, though one is honored if sent.

Statuses

UNKNOWN → PRE_TRANSIT → IN_TRANSIT → OUT_FOR_DELIVERY → DELIVERED | RETURNED | FAILED

Exception scans (customs holds, failed delivery attempts, damage) appear in events[] with isException: true, without necessarily changing the status.

Polling cadence and finalization

Carrier polling adapts to the status: ~6 h before first movement, ~2 h in transit, ~30 min out for delivery, backing off to ~12 h after 5 days without new scans.

A tracker finalizes in the cases below. On finalization, isFinalized becomes true, polling stops, and the record stays queryable:

Webhooks

Subscribe your endpoint to tracker.created, tracker.updated, or tracker.expired. They use the same signatures and retries as every SendIt webhook. There are deliberately no separate delivered or exception events: read data.object.status inside tracker.updated.

Pricing

• Only external registrations count; SendIt-generated labels never consume quota.
• Over quota, the overage is debited from your wallet at registration time (402 INSUFFICIENT_BALANCE if it can’t be covered). There is no hard cap.
• The amount charged is returned as overageCharged on the tracker.

In test mode

Registrations with a sk_test_ key never charge overage or consume quota. Test trackers progress to DELIVERED on their own with simulated data, and their webhooks carry livemode: false.

Handle errors