Skip to main content
Use the Retrieve tracking information for a parcel endpoint to retrieve a parcel’s current status and full tracking timeline using its tracking_number. This endpoint works for:

​
Calling the endpoint

To retrieve tracking information, send a GET request including the tracking number in the path:
Example request method and URL

​
Response

If successful, the API returns:
  • HTTP 200 status code
  • A Parcel Tracking object containing:
    • Parcel lifecycle timestamps:
      • created_at — When the parcel tracking object was created in Sendcloud
      • announced_at — When the parcel was handed to the carrier
      • updated_at — Last time tracking information was updated
    • details: Additional context such as expected_delivery_date, integration_id, service point indicators, return flags
    • tracking_numbers: Carrier tracking identifiers associated with the parcel.
    • events: A list of tracking events representing delivery milestones, sorted from newest to oldest. Each event includes:
      • phase: The main step of the delivery process the parcel is in, standardized across carriers, for example in_transit or delivered.
      • exception: What went wrong at this step, for example delivery_delay or address_error. none when there is no exception.
      • sub_status: Additional detail about the phase and exception, for example not_home for a failed delivery attempt. none when no additional detail applies.
      • status_type: Whether the event is a success, warning, or error.
      • description: A human-readable description of the event.
Each event has a single source. However, the full timeline may contain both carrier events and internal Sendcloud events (see Parcel Tracking Key Concepts). There is no separate top-level status field. The parcel’s current status is described by the most recent event, which is the first event in events. Check its phase first. If phase is none, the event reports an exception instead, so check exception. If Sendcloud couldn’t map a carrier status to a standardized status, phase, exception, sub_status, description, and status_type are null for that event. If the tracking number is invalid or unknown, the API returns an error response instead of a parcel object.
See the API reference for the full response schema.

​
Status definitions

Sendcloud consolidates all the variations of status messages received by different carriers into a standardized set of values. Each event describes the parcel’s status with a combination of phase, exception, and sub_status.
Migrating from API v2? The v2 Retrieve tracking information of a parcel endpoint returns a parent_status field with a human-readable status, such as At sorting centre. API v3 doesn’t return parent_status. Use the phase and exception of the most recent event (the first event in events) instead. These are machine-readable values and don’t map one-to-one to the v2 statuses. For the v2 statuses, see Tracking statuses (v2).

​
Phases

The phase field describes the main step of the delivery process. Claim events (event_type is claim) use their own phases: open, in_progress, action_required, solved_by_automation_stage, manually_solved_stage, and unknown.

​
Exceptions

The exception field describes what went wrong with the parcel. Events with an exception have phase set to none.

​
Sub-statuses

The sub_status field adds detail to a phase or exception. For example, an event with the attempted phase and the inaccessible sub-status means the carrier couldn’t deliver the parcel because the address wasn’t accessible. Common values include not_home, neighbour, mailbox, damaged, and delay. sub_status is unknown when the status of the parcel couldn’t be determined.

​
Real-time event notifications

Instead of polling this endpoint for status changes, you can receive push notifications whenever parcel events occur. The Event Subscriptions API lets you configure webhooks or third-party integrations to be notified automatically.
The Event Subscriptions API is currently in BETA.