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:

curl https://api.flexforward.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.flexforward.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.flexforward.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": "YT2503010001CN",
  "tag": "InTransit",
  "subtag": "InTransit_001",
  "subtagMessage": "In transit",
  "slug": "yunexpress",
  "checkpoints": [
    {
      "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"
    },
    {
      "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-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"
    }
  ]
}

Checkpoints are ordered with the most recent event first.

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.flexforward.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	Access denied	The label belongs to a different account
404	Label not found	Verify the label ID is correct
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