Tracking

One endpoint for agent shipments. Paste the tracking number your agent gave you and get the whole route back - warehouse and export scans in China, the flight, customs and the destination carrier's scans - as clean statuses in Polish and English.

Pass the tracking number as num (alias id). Spaces are ignored and letters are upper-cased. Events come back newest-first; summary gives the headline status so you don't have to interpret the list yourself.

GET/v1/tracking

Parameters

numreqstringThe tracking number to look up (alias: id).

Example

request
curl "https://repsapi.pl/v1/tracking?num=YT2530998211074512" \
  -H "Authorization: Bearer YOUR_KEY"
200 · response
{
  "tracking_number": "YT2530998211074512",
  "count": 3,
  "summary": {
    "stage": "flight_departed",
    "status": "Samolot z przesyłką wystartował",
    "status_en": "Flight departed",
    "delivered": false,
    "last_update": "2026-10-05 08:14:00",
    "origin_country": "CN",
    "destination_country": "PL",
    "carrier": null,
    "carrier_tracking_number": null,
    "estimated_delivery": {
      "from": "2026-10-12",
      "to": "2026-10-15",
      "based_on": 37,
      "from_stage": "flight_departed",
      "slower_than_usual": false
    }
  },
  "updates": [
    {
      "date": "2026-10-05",
      "hour": "08:14:00",
      "status": "Samolot z przesyłką wystartował",
      "status_en": "Flight departed",
      "status_original": "航班已起飞",
      "stage": "flight_departed",
      "location": "",
      "country": "CN"
    },
    {
      "date": "2026-10-04",
      "hour": "17:02:11",
      "status": "Zakończono odprawę eksportową w Chinach",
      "status_en": "Export customs clearance in China completed",
      "status_original": "出口清关完成",
      "stage": "export_customs",
      "location": "",
      "country": "CN"
    },
    {
      "date": "2026-10-02",
      "hour": "22:01:40",
      "status": "Przesyłka dotarła do magazynu spedytora",
      "status_en": "Arrived at the forwarder's warehouse",
      "status_original": "到达收货点",
      "stage": "received",
      "location": "Shenzhen",
      "country": "CN"
    }
  ],
  "source": "repsapi.pl",
  "attribution": "Data provided by repsapi.pl",
  "docs": "https://repsapi.pl/docs"
}

Summary fields

  • stage - where the parcel is now (see stages below).
  • status / status_en - the headline status in Polish / English.
  • delivered - true once any scan says delivered.
  • last_update - time of the newest scan, YYYY-MM-DD HH:MM:SS.
  • origin_country / destination_country - ISO codes, or null.
  • carrier / carrier_tracking_number - the destination carrier and its own number, when known (use it on the carrier's site too).
  • estimated_delivery - the likely delivery window, or null (see below).

Estimated delivery

For parcels on their way, summary.estimated_delivery tells you when they will most likely arrive. It comes from our own history: how long delivered parcels from the same forwarder to the same country took from the stage this parcel is at now. The window is the middle half of those times.

  • from / to - first and last likely delivery day (YYYY-MM-DD).
  • based_on - how many delivered parcels the estimate uses (at least 5).
  • from_stage - the stage the estimate counts from.
  • slower_than_usual - true when the parcel is already past the usual window.

It is null for delivered, returned and waiting-for-pickup parcels, and while we don't have enough history for the route. We keep only anonymous journeys (stage dates, country, forwarder) - never the tracking number or any personal data.

Follow parcels in the dashboard

Signed-in users can add parcels under Dashboard → Parcels. While the site is open we check them every few minutes and show a notification in the corner when the status changes. These checks don't count toward your API quota.

Update fields

  • status - the scan in Polish.
  • status_en - the scan in English.
  • status_original - the scan exactly as the source wrote it (often Chinese).
  • stage - machine-readable stage of this scan.
  • date / hour - YYYY-MM-DD / HH:MM:SS, local time of the scan.
  • location - city or facility, empty when the source gives none.
  • country - ISO country code, or null if unknown.

Stages

  • info_received - the forwarder or carrier has the shipment data.
  • received - arrived at the forwarder's warehouse in China.
  • in_transit - moving between warehouses, hubs or depots.
  • export_customs - export customs clearance in China.
  • awaiting_flight - handed to the airline / flight booked.
  • delayed - flight delayed or cancelled.
  • flight_departed - the flight has left.
  • flight_arrived - landed, unloading.
  • import_customs - import customs clearance.
  • last_mile - with the destination carrier, before delivery.
  • out_for_delivery - on the courier's van.
  • ready_for_pickup - waiting at a pickup point or parcel locker.
  • delivered - delivered or collected.
  • exception - failed delivery, customs hold or another problem.
  • returned - on its way back to the sender.

Results are cached briefly (a few minutes while the parcel moves, longer once it's delivered), so polling more often than every few minutes won't return anything newer. When the number isn't recognised yet the API returns 200 with an empty updates array (count: 0, summary: null) rather than an error.

Try it without code

The same parcel tracking runs on repsapi.pl/tools/tracking - no key needed.