Poll tracking updates

Use GET /tracking/{id} to retrieve real-time shipment tracking data in a unified format. This guide covers the polling flow, how to interpret tracking statuses, and patterns for building customer notifications.

Retrieve tracking data

Use the id from the label creation response. {id} accepts the label UUID or your customerOrderNumber; it does not accept the courier tracking number (courierTrackingNumber), which returns 404:

curl https://api.flexforwardship.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN"

const response = await fetch(
  'https://api.flexforwardship.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
  { headers: { 'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN' } }
);
const tracking = await response.json();
console.log(tracking.tag); // High-level status: InTransit, Delivered, etc.

import requests

response = requests.get(
    'https://api.flexforwardship.com/tracking/f47ac10b-58cc-4372-a567-0e02b2c3d479',
    headers={'x-rr-apikey': 'YOUR_API_KEY', 'x-rr-apitoken': 'YOUR_API_TOKEN'}
)
tracking = response.json()
print(tracking['tag'])  # High-level status: InTransit, Delivered, etc.

Response

200 OK

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "trackingNumber": "YT2503010001TN",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "checkpointTime": "2026-03-15T10:30:00Z",
      "city": "Tokyo",
      "state": "Tokyo",
      "countryRegion": "JP",
      "location": null,
      "message": "Shipment information received",
      "tag": "InfoReceived",
      "subtag": "InfoReceived_001",
      "subtagMessage": "Shipment information received",
      "slug": "yunexpress"
    },
    {
      "checkpointTime": "2026-03-16T02:30:00Z",
      "city": "Shenzhen",
      "state": "Guangdong",
      "countryRegion": "CN",
      "location": null,
      "message": "Departed from sorting center",
      "tag": "InTransit",
      "subtag": "InTransit_001",
      "subtagMessage": "In transit",
      "slug": "yunexpress"
    },
    {
      "checkpointTime": "2026-03-17T08:15:00Z",
      "city": "Los Angeles",
      "state": "CA",
      "countryRegion": "US",
      "location": "LAX Distribution Center",
      "message": "Arrived at destination country",
      "tag": "InTransit",
      "subtag": "InTransit_001",
      "subtagMessage": "In transit",
      "slug": "yunexpress"
    }
  ]
}

Checkpoints are ordered chronologically, oldest event first. The last element is the most recent event.

Understand the tracking status

Use the top-level tag field for high-level status logic:

Tag	Customer-facing meaning	Action
`Pending`	Order is being processed	No notification needed
`InfoReceived`	Shipment registered with courier	Notify: “Your order has shipped”
`InTransit`	Package is on the way	Notify: “Your package is in transit”
`Delivered`	Package delivered	Notify: “Your package has been delivered”
`Exception`	Delivery issue	Notify: “There’s an issue with your delivery” and investigate
`Cancelled`	Shipment cancelled	Handle internally
`Unknown`	Status unavailable	No notification — retry later

Polling pattern

Since webhooks are not currently available, poll GET /tracking/{id} at a reasonable interval to detect status changes.

Recommended approach

async function pollTracking(labelId, apiKey, apiToken) {
  let lastTag = null;

  const interval = setInterval(async () => {
    const response = await fetch(
      `https://api.flexforwardship.com/tracking/${labelId}`,
      { headers: { 'x-rr-apikey': apiKey, 'x-rr-apitoken': apiToken } }
    );
    const tracking = await response.json();

    if (tracking.tag !== lastTag) {
      lastTag = tracking.tag;
      await notifyCustomer(tracking); // Your notification logic
    }

    // Stop polling when shipment reaches a terminal state
    if (['Delivered', 'Cancelled'].includes(tracking.tag)) {
      clearInterval(interval);
    }
  }, 30 * 60 * 1000); // Every 30 minutes
}

Polling guidelines

Shipment stage	Recommended interval
`Pending` / `InfoReceived`	Every 4–6 hours
`InTransit`	Every 30–60 minutes
`Delivered` / `Cancelled`	Stop polling
`Exception`	Every 15–30 minutes until resolved

Tracking data is fetched from the courier in near-real-time. Polling more frequently than every 15 minutes is unlikely to yield new data and counts against the recommended rate limit of 10 requests per second.

Error handling

Status	Meaning	Action
200	Tracking data retrieved	Process the `tag` and `checkpoints`
403	Account access denied	Your account is not permitted to call the API (for example, a blocked account)
404	Label not found	No label with that UUID or `customerOrderNumber` exists in your account. Labels owned by other accounts are also reported as 404.
502	Upstream service error	Retry with exponential backoff

Getting Started

Guides

Use-Case Guides

Platform

Poll Tracking Updates

Poll tracking updates

Retrieve tracking data

Response

Understand the tracking status

Polling pattern

Recommended approach

Polling guidelines

Error handling

Next steps

Core Concepts

Idempotency and Retries

​Poll tracking updates

​Retrieve tracking data

​Response

​Understand the tracking status

​Polling pattern

​Recommended approach

​Polling guidelines

​Error handling

​Next steps

Core Concepts

Idempotency and Retries

Poll tracking updates

Retrieve tracking data

Response

Understand the tracking status

Polling pattern

Recommended approach

Polling guidelines

Error handling

Next steps