Documentation

Register tracking numbers via Trackings API

The Trackings API provides a scalable, webhook‑driven approach to Royal Mail shipment tracking. By registering tracking numbers explicitly, customers gain proactive shipment visibility while maintaining control over tracking duration, volume, and costs.

Register Royal Mail tracking numbers with the Trackings API to receive webhook updates for eligible shipments created outside your standard INTERSOFT tracking flow.

🚧

Important

This endpoint is only supported for Royal Mail shipments and is a chargeable API feature. Customers should ensure tracking registration is performed only when required to avoid unnecessary costs.

INTERSOFT monitors each registered tracking number and pushes new events to your configured webhook for a defined tracking period.

Use this endpoint when you need:

  • Automated shipment visibility
  • Event‑driven tracking updates
  • Integration‑based tracking without polling APIs

Royal Mail only

This endpoint supports Royal Mail shipments only.

30-day tracking window

Tracking updates are retained and pushed for up to 30 days from registration.

Batch Processing

Submit up to 1,000 tracking numbers in a single POST /v4/trackings request.

How it works

  1. Create a Royal Mail shipment, or obtain valid Royal Mail tracking numbers.
  2. Register the tracking numbers by submitting them to POST /v4/trackings.
  3. INTERSOFT begins monitoring the registered shipments.
  4. INTERSOFT pushes tracking updates to your webhook endpoint as events occur.

Tracking window and delivery behaviour

  • Tracking updates are retained and pushed for up to 30 days from registration.
  • After the 30‑day tracking window expires, updates for the registered tracking numbers are no longer generated.
  • Real-time tracking updates are delivered through webhook notifications.
  • No historical tracking events are sent when a tracking number is registered. INTERSOFT pushes only events that occur after registration.

Retry behaviour

If your webhook endpoint is temporarily unavailable, INTERSOFT retries delivery for up to 72 hours. After the retry window expires, undelivered events are discarded.

Supported Royal Mail products

Tracking registration is supported only for the following Royal Mail trackable services:

Domestic services

  • Tracked Standard
  • Tracked High Volume
  • Tracked Returns
  • Special Delivery

International services

  • International Tracked
  • International Signed
  • International Tracked and Signed

Tracking registration requests submitted for unsupported products will not return tracking updates.

Handle invalid tracking numbers

If a batch contains invalid tracking numbers, the Trackings API continues processing the valid ones and reports the invalid entries separately.

Processing behaviour

  • All tracking numbers in a request are accepted and inserted into the database, up to 1,000 entries per request.
  • Invalid tracking numbers are marked as DO NOT TRACK and are not registered with the carrier.
  • The request does not fail when invalid numbers are present.
  • Duplicate tracking numbers within the same batch are accepted.

Invalid tracking event

For each invalid tracking number, Intersoft creates a tracking event and pushes it to your webhook.

Event properties

  • Event code: INVD
  • Event name: Invalid Tracking Number
  • Event type: Tracking
  • Milestone: No
  • Stop the clock: Yes
📘

Note

The webhook payload includes the mandatory fields shown in the push payload example. Invalid tracking numbers are processed asynchronously so valid shipments continue tracking without interruption.

See also

Add Tracking Account

Establish your tracking account for seamless integration.

Track Events and Milestones

Understand tracking events and milestone data.

Handle Webhook Suspension

Manage and resolve webhook suspension scenarios.


Updated 10 days ago