Quickstart

Tracksuite provides unified multi-carrier shipment tracking. With the Tracksuite API, you can create trackings and query their current status and complete timeline. Combined with webhooks, your system can automatically receive changes for order synchronization and post-purchase tracking experiences.

This guide is for developers integrating Tracksuite for the first time. Three practical integration use cases explain how the Tracksuite API works and how to use the API and webhooks together.

1. Get your API key

Tracksuite uses an API key to identify and authenticate users. To authenticate, include your key in the Authorization request header.

The API key is generated automatically when the account is registered. To retrieve it:

2. API endpoint

All Gateway API endpoints use the following base URL and HTTPS:

https://api.tracksuite.net

3. Common use cases

The following three use cases form a complete shipment-tracking integration.

Use case 1: Create a tracking

In this documentation, a “tracking” is a shipment tracking record in Tracksuite containing a business identifier, tracking number, and optional carrier code.

To create a tracking, provide referId and rawTrackingNumber. referId comes from your own system, such as an order ID. rawTrackingNumber is the tracking number from the carrier. You can omit metadata.carrierCode; Tracksuite will identify the carrier from the tracking number.

Method 1: v1 batch creation

POST https://api.tracksuite.net/api/v1/routers/create

Each request creates 1–40 trackings and returns real-time tracking information. This example creates one USPS tracking:

curl 'https://api.tracksuite.net/api/v1/routers/create' \
  -H 'Authorization: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"data":[{"referId":"order-10001","rawTrackingNumber":"9400111899223857461234","metadata":{"carrierCode":"usps"}}]}'

Method 2: v2 asynchronous creation

POST https://api.tracksuite.net/api/v2/trackings/create

Each request creates 1–1000 trackings. After the request is accepted, Tracksuite processes the batch asynchronously:

curl 'https://api.tracksuite.net/api/v2/trackings/create' \
  -H 'Authorization: your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"data":[{"referId":"order-10002","rawTrackingNumber":"9400111899223857465678","metadata":{"carrierCode":"usps"}}]}'

A successful request means the batch has entered asynchronous processing. Retrieve each tracking result through the query API or a Webhook.

Use case 2: Query status and timeline

After creating a tracking, query by referId or tracking number. Using referId maps the result directly to the order in your system.

This example queries the order-10001 tracking created above:

curl 'https://api.tracksuite.net/api/v1/routers/detail?referId=order-10001' \
  -H 'Authorization: your_api_key'

If you use method 2 and asynchronous processing is not finished, the query returns "message": "Processing". Query again later or wait for a webhook update.

Use case 3: Receive tracking updates

To stay up to date on shipment progress, you can repeatedly call the query API for the latest status. If you want proactive notifications and want to avoid unnecessary API calls when tracking information has not changed, we recommend using webhooks. With Tracksuite, you can receive all tracking updates through webhooks, or only the shipment statuses you select.

Sign in to the Tracksuite Portal, go to the API & Webhooks section in Settings, and configure your endpoint URL to receive notifications.

For security, add the webhook secret provided on the same page to enable SHA256 signature verification.

After you save the endpoint, your server will receive a delivery like this:

[
  {
    "eventId": "8f2c1e6a-4b3d-4c91-9a10-2d7f6e5c8b11",
    "event": "router.delivered",
    "eventTime": "2026-07-10T12:05:00.000Z",
    "data": {
      "trackingNumber": "9400111899223857461234",
      "status": 1,
      "statusTrack": "delivered",
      "routerId": "550e8400-e29b-41d4-a716-446655440000",
      "summary": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "trackingNumber": "9400111899223857461234",
        "status": 1,
        "statusLabel": "DELIVERED",
        "latestEvent": "Delivered",
        "latestCheckpointTime": "2026-07-10T12:00:00.000Z",
        "transitTime": 5,
        "created": "2026-07-07T09:00:00.000Z",
        "updated": "2026-07-10T12:05:00.000Z"
      },
      "detail": {
        "trackingNumber": "9400111899223857461234",
        "statusSummary": "Delivered",
        "trackingEvents": [
          {
            "eventType": "Delivered",
            "eventCity": "LAS VEGAS",
            "eventState": "NV",
            "eventZIPCode": "89101",
            "eventTimestamp": "2026-07-10T05:00:00",
            "GMTTimestamp": "2026-07-10T12:00:00Z"
          },
          {
            "eventType": "Out for Delivery",
            "eventCity": "LAS VEGAS",
            "eventState": "NV",
            "eventZIPCode": "89101",
            "eventTimestamp": "2026-07-10T02:10:00",
            "GMTTimestamp": "2026-07-10T09:10:00Z"
          },
          {
            "eventType": "In Transit to Next Facility",
            "eventCity": "LAS VEGAS",
            "eventState": "NV",
            "eventZIPCode": "89101",
            "eventTimestamp": "2026-07-09T18:20:00",
            "GMTTimestamp": "2026-07-10T01:20:00Z"
          }
        ]
      },
      "error": null
    }
  }
]