Skip to main content
Use the Create a tracking-only parcel endpoint to register a parcel in Sendcloud for tracking-only visibility, 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 a tracking-only parcel 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 a tracking-only parcel 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_withDefines the shipping_option_code used for this parcel. Even though no shipment is created, this provides context about the carrier service used.
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 tracking-only 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.

​
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.