Trackora API Documentation

The Trackora REST API lets developers integrate real-time package tracking into any application. Query statuses from 1,000+ carriers across 190+ countries, manage saved parcels programmatically, and receive webhook notifications when shipment statuses change. API access is available to all Premium subscribers.

Authentication

Every request to the Trackora API must include a valid API key in the HTTP Authorization header. API keys are long-lived bearer tokens you generate in the API Keys section of your account settings. Treat your key like a password — it grants full access to your Trackora account data.

Authorization: Bearer YOUR_API_KEY

Requests without a valid key return 401 Unauthorized. Keys can be revoked at any time from the account settings page without affecting other keys. We recommend creating one key per integration rather than sharing a single key across multiple systems, so a compromised key can be revoked without disrupting others.

Base URL

https://trackoraapp.com/api/v1

All endpoints are versioned under /v1. The API returns JSON for all responses. Request bodies for POST and PATCH endpoints must use Content-Type: application/json.

Core Endpoints

Track a Package by Tracking Number

GET /api/v1/track/{tracking_number}

Looks up the current status and full movement history for a tracking number. The system automatically detects the carrier; you do not need to specify it. The response includes the current status (e.g. In Transit, Out for Delivery, Delivered), a timestamped list of tracking events, the detected carrier name and slug, origin and destination country codes, and an estimated delivery date when the carrier provides one.

This endpoint fetches a fresh status from the carrier on each call for Premium users. For free-tier API consumers, a cached response from the last poll cycle is returned.

List Saved Parcels

GET /api/v1/shipments

Returns all parcels saved in your Trackora account, including their current status, user-defined labels, notes, and the date each parcel was added. Supports optional query parameters: archived=true to include archived parcels, status=in_transit to filter by status, and limit / offset for pagination. The default page size is 50 parcels.

Add a Parcel

POST /api/v1/shipments

Saves a new parcel to your account for ongoing tracking. The request body must include trackingNumber (string, required). Optional fields are label (a human-readable name, e.g. "Blue jacket from AliExpress"), note (free text), and carrierId (force a specific carrier slug if auto-detection gives an unexpected result). The response returns the newly created parcel object including the assigned internal ID.

Update a Parcel

PATCH /api/v1/shipments/{id}

Updates the label, note, or archived state of an existing parcel. Only the fields included in the request body are modified. Use "archived": true to move a delivered parcel out of the active list without deleting it.

Delete a Parcel

DELETE /api/v1/shipments/{id}

Permanently removes a parcel and its tracking history from your account. This action cannot be undone. Returns 204 No Content on success.

Rate Limits

Rate limits are applied per API key and reset at midnight UTC each day.

• Free plan: 100 requests per day across all endpoints
• Premium plan: 10,000 requests per day; burst allowance of 60 requests per minute

When a rate limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating the number of seconds until the limit resets. The current usage counters for your key are returned in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers on every call.

Error Codes

• 400 Bad Request — missing or invalid request body field
• 401 Unauthorized — missing, invalid, or revoked API key
• 404 Not Found — tracking number not found or parcel ID does not belong to your account
• 422 Unprocessable Entity — tracking number format is valid but the carrier returned no data
• 429 Too Many Requests — rate limit exceeded
• 503 Service Unavailable — carrier API is temporarily unreachable; retry after the interval in the Retry-After header

Frequently Asked Questions

Do I need a Premium subscription to use the API?

Yes. API key generation requires an active Premium subscription. Free accounts can use the Trackora web interface and mobile apps but cannot generate API keys. See pricing plans for details.

How do I get my API key?

Sign in to your account, open Settings, and go to the API Keys tab. Click Generate New Key, give it a descriptive name, and copy the key — it is only shown once at creation time.

Can I use the API to track a number without saving it?

Yes. The GET /api/v1/track/{tracking_number} endpoint performs a live lookup without adding the parcel to your account. Nothing is stored unless you call the POST /shipments endpoint explicitly.

Which carriers are supported?

All 1,000+ carriers available in the Trackora web app are accessible via the API, including AliExpress, China Post, DHL, FedEx, USPS, CDEK, Nova Poshta, PostNL, and hundreds of regional carriers. The complete carrier list is available at carrier pages.

Pricing Plans · Service Status · Trackora — Home