> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating an external parcel for tracking

Use the [Create an external parcel for tracking](/api/v3/parcel-tracking/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.

<Note>
  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.
</Note>

## Before you begin

To use this endpoint, you must:

1. Make sure you’ve completed basic account setup. See the [Quickstart guide](/docs/getting-started).
2. Authenticate using API credentials (Basic auth) or OAuth2 client credentials. See [Authentication](/docs/getting-started/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](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) endpoint, send a `POST` request to:

```http Example request method and URL theme={null}
POST https://panel.sendcloud.sc/api/v3/parcels/tracking
```

### Required parameters

To register a parcel for tracking, the following fields are required:

| Status            | Description                                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `announced_at`    | The date and time the parcel was handed over to the carrier (ISO 8601 format). This establishes the starting point of the tracking lifecycle.                                    |
| `from_address`    | The 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_address`      | The recipient’s address object. At minimum, this includes: `address_line_1`, `postal_code`, `country_code`.                                                                      |
| `ship_with`       | Provides information about which contract and shipping method were used to ship the parcel.                                                                                      |
| `tracking_number` | Contains: `carrier_code` (Sendcloud carrier identifier), `tracking_number` (carrier-provided tracking number). This is the primary identifier used to retrieve tracking updates. |
| `source_id`       | A unique identifier from your own system. Use this to link the external parcel back to your internal order or shipment record.                                                   |

<Note>No prior Sendcloud shipment or parcel ID is required — the API will register the parcel independently.</Note>

<Info>
  To see the parcel in [Analytics](https://support.sendcloud.com/hc/en-us/sections/28788521497745-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](/docs/shipments/shipping-options-and-quotes).
</Info>

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

<Info>
  See the [API reference](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) for the full structure on both
  required and optional fields.
</Info>

## 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](/docs/parcel-tracking/retrieve-tracking-info) 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 missing authentication credentials

See the [API reference](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) for full error response details.