Skip to main content
Use the Create an external parcel for tracking endpoint to register an external parcel in Sendcloud for parcel tracking, using a valid tracking number and parcel details. This does not create a shipment or label in Sendcloud. It registers the parcel so you can retrieve its tracking events and status via the Parcel Tracking API.
The Create an external parcel for tracking endpoint is currently in beta. While the core functionality is stable, some details or behavior may change as the feature evolves. We recommend reviewing release notes periodically for updates.

​
Before you begin

To use this endpoint, you must:
  1. Make sure you’ve completed basic account setup. See the Quickstart guide.
  2. Authenticate using a Bearer token. See OAuth2 authentication.
  3. Have a valid tracking number and carrier code for the parcel you want to track.

​
Calling the endpoint

To create an external parcel for tracking endpoint, send a POST request to:
Example request method and URL
POST https://panel.sendcloud.sc/api/v3/parcels/tracking

​
Required parameters

To register a parcel for tracking, the following fields are required:
StatusDescription
announced_atThe date and time the parcel was handed over to the carrier (ISO 8601 format). This establishes the starting point of the tracking lifecycle.
from_addressThe sender’s address object. At minimum, this includes: address_line_1, postal_code, country_code. This is used for validation and carrier tracking context.
to_addressThe recipient’s address object. At minimum, this includes: address_line_1, postal_code, country_code.
ship_withProvides information about which contract and shipping method were used to ship the parcel.
tracking_numberContains: carrier_code (Sendcloud carrier identifier), tracking_number (carrier-provided tracking number). This is the primary identifier used to retrieve tracking updates.
source_idA unique identifier from your own system. Use this to link the external parcel back to your internal order or shipment record.
No prior Sendcloud shipment or parcel ID is required — the API will register the parcel independently.
To see the parcel in Analytics, include the shipping_option_code in the ship_with property. Parcels created without a shipping option code will not appear in analytics. You can retrieve valid shipping option codes via the Shipping Options API.

​
Optional parameters

You may optionally include additional contextual information:
  • details: Additional parcel metadata such as: brand_id, expected_delivery_date, Service point flags
  • parcel_items: List of items included in the parcel. Useful for reporting and internal tracking.
  • measurements: Parcel dimensions and weight. Helpful for logistics analytics and reporting.
  • insurance: Insurance policy information if applicable.
  • return_price: Return price context if relevant.
See the API reference for the full structure on both required and optional fields.

​
Response

If the request is successful, it’ll include:
  • HTTP 200 status code
  • A Parcel Tracking object containing:
    • created_at: When the tracking object was created in Sendcloud
    • announced_at: When the parcel was handed to the carrier
    • updated_at: Last time tracking data was updated
    • tracking_numbers — Carrier tracking identifiers
    • from_address and to_address
    • ship_with
    • details (if available)
    • parcel_items (if provided)
This object can later be queried using the Retrieve tracking information for a parcel endpoint.

​
Error Handling

If required fields are missing or invalid, the API returns an error response. Common causes include:
  • Missing required nested fields in from_address / to_address
  • Invalid tracking_number format or missing carrier code
  • Missing ship_with.properties.shipping_option_code
  • Invalid or expired Bearer token
See the API reference for full error response details.