Introduction
Good news for FaaS sellers: parcel tracking information is now available via API.
Sellers can now retrieve carrier tracking data for their outbound shipments directly through the Octopia API — without needing to visit carrier portals or parse carrier notifications. The new endpoint exposes the full delivery timeline as reported by the carrier, from the moment a parcel is handed over until final delivery or return.
What changed?
Sellers can now:
- retrieve the current tracking status of any parcel associated with an outbound shipment
- access the full history of carrier status events for each parcel
- filter parcel trackings by tracking number, order reference, or status
- get the direct carrier tracking URL to share with end customers
The API exposes the following parcel tracking statuses:
| Status | Description |
| CarrierInfoReceived | Shipping request received by the carrier, parcel not yet processed |
| InTransit | Parcel is in transit |
| PostponedDelivery | Delivery postponed (client absence, rescheduling, etc.) |
| AvailableForPickup | Parcel is available for pickup |
| Delivered | Parcel has been delivered to the recipient |
| ReturnToSender | Parcel is being returned to the sender |
| NotFound | Parcel not yet recognized by the carrier |
| Rejected | Parcel tracking is not possible |
Example
- Retrieve all trackings for a specific order: GET /parcel-trackings?orderReference=69667758758NXP
- Look up a parcel by its carrier tracking number: GET /parcel-trackings?parcelTrackingNumber=XY123456789FR
- Filter by status to identify delayed parcels: GET /parcel-trackings?parcelTrackingStatus=PostponedDelivery
Results are paginated using cursor-based pagination (default: 10 items per page, max: 100).
To correlate parcel tracking data with your outbound shipment data, use the following field mappings:
| Outbound API field | Parcel Tracking API field |
| reference | orderReference |
| parcel.carrierParcelId | parcelTrackingNumber |
Important notes
- Tracking data is available once the parcel reaches the Shipped status in the Outbound API.
- Data is refreshed every 8 hours. The updatedAt field reflects the timestamp of the last synchronization with the carrier — there is no real-time tracking.
- A NotFound status does not necessarily indicate an error: the carrier may not have registered the parcel yet. Retry after the next refresh window.
- For shipments with multiple parcels, each parcel has its own independent tracking record.
Why it matters
This new endpoint makes it possible to automate post-shipment workflows directly from seller systems such as OMS, ERP, or customer service tools. It gives sellers and their customer service teams accurate, up-to-date visibility on parcel progress — enabling proactive communication with end customers and faster resolution of delivery issues.