Skip to main content
POST
/
parcels
/
tracking
Create an external parcel for tracking
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/parcels/tracking \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "announced_at": "2024-01-01T00:00:00Z",
  "details": {
    "brand_id": 123,
    "integration_id": 456,
    "is_return": false
  },
  "from_address": {
    "address_line_1": "33 rue de Stalingrad",
    "address_line_2": "",
    "city": "Cermenate",
    "company_name": "Company",
    "country_code": "IT",
    "email": "billing@mail.com",
    "house_number": "45",
    "name": "Laurent Kuchto",
    "phone_number": "",
    "po_box": "12345",
    "postal_code": "78500",
    "state_province_code": "IT-CO"
  },
  "insurance": {
    "currency": "EUR",
    "policy_id": "POL123",
    "value": 500
  },
  "parcel_items": [
    {
      "description": "T-Shirt XL",
      "hs_code": "620520",
      "intended_use": "Personal use",
      "item_id": "5552",
      "material_content": "100% Cotton",
      "mid_code": "NLOZR92MEL",
      "origin_country": "NL",
      "product_id": "19284",
      "properties": {
        "color": "green",
        "size": "red"
      },
      "quantity": 1,
      "sku": "TS1234",
      "price": {
        "currency": "EUR",
        "value": "6.15"
      },
      "weight": {
        "unit": "kg",
        "value": 6
      }
    }
  ],
  "measurements": {
    "dimension": {
      "height": 3,
      "length": 2,
      "unit": "m",
      "width": 4
    },
    "volume": {
      "unit": "cm3",
      "value": 35
    },
    "weight": {
      "unit": "g",
      "value": 82
    }
  },
  "return_price": {
    "currency": "EUR",
    "value": "76.64"
  },
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "contract_id": 517,
      "shipping_option_code": "postnl:standard"
    }
  },
  "shipment": {
    "external_reference_id": "REF123",
    "order": {
      "order_number": "ORD123",
      "source_external_id": "EXT789",
      "source_id": "order_456",
      "total_order_price": {
        "currency": "EUR",
        "value": "76.64"
      }
    },
    "price": {
      "currency": "EUR",
      "value": "76.64"
    },
    "source_id": "shipment_789"
  },
  "source_id": "1234",
  "to_address": {
    "address_line_1": "33 rue de Stalingrad",
    "address_line_2": "",
    "city": "Cermenate",
    "company_name": "Company",
    "country_code": "IT",
    "email": "billing@mail.com",
    "house_number": "45",
    "name": "Laurent Kuchto",
    "phone_number": "",
    "po_box": "12345",
    "postal_code": "78500",
    "state_province_code": "IT-CO"
  },
  "tracking_number": {
    "carrier_code": "dhl",
    "tracking_number": "TRACK123456789",
    "tracking_url": "https://track.carrier.com/TRACK123456789"
  }
}
'
{
  "announced_at": "2024-01-01T00:00:00Z",
  "created": true,
  "created_at": "2024-01-01T00:00:00Z",
  "details": {
    "brand_id": 123,
    "integration_id": 456,
    "is_return": false
  },
  "from_address": {
    "address_line_1": "33 rue de Stalingrad",
    "address_line_2": "",
    "city": "Cermenate",
    "company_name": "Company",
    "country_code": "IT",
    "email": "billing@mail.com",
    "house_number": "45",
    "name": "Laurent Kuchto",
    "phone_number": "",
    "po_box": "12345",
    "postal_code": "78500",
    "state_province_code": "IT-CO"
  },
  "parcel_items": [
    {
      "description": "T-Shirt XL",
      "hs_code": "620520",
      "intended_use": "Personal use",
      "item_id": "5552",
      "material_content": "100% Cotton",
      "mid_code": "NLOZR92MEL",
      "origin_country": "NL",
      "product_id": "19284",
      "properties": {
        "color": "green",
        "size": "red"
      },
      "quantity": 1,
      "sku": "TS1234",
      "source_id": "123abc",
      "price": {
        "currency": "EUR",
        "value": "6.15"
      },
      "weight": {
        "unit": "kg",
        "value": 0.4
      }
    }
  ],
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "contract_id": 517,
      "shipping_option_code": "postnl:standard"
    }
  },
  "source_id": "1234",
  "to_address": {
    "address_line_1": "33 rue de Stalingrad",
    "address_line_2": "",
    "city": "Cermenate",
    "company_name": "Company",
    "country_code": "IT",
    "email": "billing@mail.com",
    "house_number": "45",
    "name": "Laurent Kuchto",
    "phone_number": "",
    "po_box": "12345",
    "postal_code": "78500",
    "state_province_code": "IT-CO"
  },
  "tracking_numbers": [
    {
      "carrier_code": "dhl",
      "tracking_number": "TRACK123456789",
      "tracking_url": "https://track.carrier.com/TRACK123456789"
    }
  ]
}
Register a parcel in the Sendcloud system exclusively for tracking, without creating a shipment label. This is useful when you create labels outside of Sendcloud but still want to track the parcels within the platform. Provide the tracking number, carrier, sender and recipient addresses, and optionally include parcel items, measurements, and insurance details.
This endpoint is currently in beta. While the core functionality is stable, some details or behavior may change as the API is finalized. Review your integration periodically and check release notes for updates.
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.

Authorizations

​
Authorization
string
header
required

Basic Authentication using API key and secrets is currently the main authentication mechanism.

Body

application/json

The Parcel Tracking Create Request object

​
announced_at
string<date-time>
required

The timestamp of when the parcel was announced to the carrier (label was created)

​
from_address
Parcel Tracking Address · object
required

Parcel Tracking Address object

​
ship_with
Ship With Shipping Option Code Object · object
required

Ship using a shipping option code. The shipping option code is required.

Example:
{
  "type": "shipping_option_code",
  "properties": {
    "shipping_option_code": "postnl:standard/insured=3000",
    "contract_id": 517,
    "user_shipping_method_name": "Express Delivery",
    "user_shipping_method_id": "express-001"
  }
}
​
shipment
Shipment Create Request · object
required
​
source_id
string
required

An external identifier that clients can provide to link the parcel with the corresponding record in their own system

​
to_address
Parcel Tracking Address · object
required

Parcel Tracking Address object

​
tracking_number
Tracking Number Create Request · object
required

The request object for the Tracking Number

​
details
Parcel Detail Create Request · object
​
insurance
Insurance · object

Sendcloud Insurance object with insurance policy ID

​
parcel_items
Parcel Item Object · object[]

List of items / products that the parcel contains

​
measurements
Measurement Object · object

This object provides essential information for accurate packing, shipping, and inventory management

​
return_price
Price object · object

Price, consisting of a value and currency.

Response

Successful Response

The Parcel Tracking Create Response object

​
announced_at
string<date-time>
required

The timestamp of when the parcel was announced to the carrier (label was created)

​
created
boolean
required

Indicates whether the parcel was newly created (true) or already existed (false). The endpoint is idempotent — submitting the same source_id, carrier_code, and organization will return the existing parcel with created set to false.

​
created_at
string<date-time>
required

The timestamp of when the parcel was created in the system

​
details
Parcel Detail Response · object
required
Example:
{
  "brand_id": 123,
  "expected_delivery_date": "2025-01-04",
  "integration_id": 456,
  "is_mail_box": false,
  "is_return": false,
  "is_to_service_point": false
}
​
from_address
Parcel Tracking Address · object
required

Parcel Tracking Address object

​
ship_with
Ship With Shipping Option Code Object · object
required

Ship using a shipping option code. The shipping option code is required.

Example:
{
  "type": "shipping_option_code",
  "properties": {
    "shipping_option_code": "postnl:standard/insured=3000",
    "contract_id": 517,
    "user_shipping_method_name": "Express Delivery",
    "user_shipping_method_id": "express-001"
  }
}
​
source_id
string
required

An external identifier that clients can provide to link the parcel with the corresponding record in their own system

​
to_address
Parcel Tracking Address · object
required

Parcel Tracking Address object

​
tracking_numbers
Tracking Number Response · object[]
required
​
parcel_items
Parcel Item with Source ID Object · object[]

List of items / products that the parcel contains