Skip to main content
POST
/
parcels
curl --request POST \
  --url https://panel.sendcloud.sc/api/v2/parcels \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parcel": {
    "name": "John Doe",
    "company_name": "Sendcloud",
    "address": "Stadhuisplein",
    "house_number": "10",
    "city": "Eindhoven",
    "postal_code": "5611 EM",
    "telephone": "+31612345678",
    "request_label": true,
    "email": "john@doe.com",
    "data": {},
    "country": "NL",
    "shipment": {
      "id": 8
    },
    "weight": "10.000",
    "order_number": "1234567890",
    "insured_value": 0,
    "total_order_value_currency": "GBP",
    "total_order_value": "11.11",
    "quantity": 1,
    "shipping_method_checkout_name": "DHL Express Domestic"
  }
}
'
{
  "parcel": {
    "id": 3,
    "name": "John Doe",
    "company_name": "Sendcloud",
    "contract": 1,
    "address": "Stadhuisplein 10",
    "address_divided": {
      "street": "Stadhuisplein",
      "house_number": "10"
    },
    "city": "Eindhoven",
    "postal_code": "5611 EM",
    "telephone": "0612345678",
    "email": "",
    "date_created": "01-01-2018 21:45:30",
    "date_updated": "01-01-2018 21:47:12",
    "date_announced": "01-01-2018 21:47:13",
    "tracking_number": "S0M3TR4Ck1NgNumB3r",
    "weight": "2.000",
    "label": {
      "normal_printer": [
        "https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4",
        "https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4",
        "https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4",
        "https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4"
      ],
      "label_printer": "https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4"
    },
    "documents": [
      {
        "type": "label",
        "size": "a6",
        "link": "https://panel.sendcloud.sc/api/v2/parcels/3/documents/label"
      }
    ],
    "status": {
      "id": 0,
      "message": "Ready to send"
    },
    "data": {},
    "country": {
      "iso_3": "NLD",
      "iso_2": "NL",
      "name": "Netherlands"
    },
    "shipment": {
      "id": 1,
      "name": "PostNL Standard 0-23kg"
    },
    "carrier": {
      "code": "postnl"
    },
    "is_return": false,
    "total_order_value_currency": "GBP",
    "total_order_value": "11.11",
    "colli_uuid": "88296eff-595c-4c62-9b6f-075112bf54f6",
    "collo_nr": 0,
    "collo_count": 1,
    "awb_tracking_number": null,
    "box_number": null,
    "length": null,
    "width": null,
    "height": null,
    "shipping_method_checkout_name": "DHL Express Domestic",
    "reference": "some_reference_123"
  }
}
This endpoint creates a parcel under your API credentials.
  • You can choose to announce the parcel and create the shipping label at the same time as you create the parcel by providing the parameter request_label: true.
  • When request_label is false, the parcel will be created, but not announced.
  • You can then request the shipping label at a later date by changing the request_label parameter via the Update a parcel endpoint.
Make sure you use the correct sender_address if you wish to ship this parcel from a location other than your default sender address. You can find the sender_address for each of the addresses you’ve saved in your Sendcloud account via the Retrieve a sender address endpoint.
Also keep in mind that the sender_address id will not be saved/reflected in the created order (Incoming Orders view / Pack & Go) if request_label is false.

​
International parcel creation

If you want to create a parcel to ship to a destination country outside the EU, it’s mandatory to include additional information related to the parcel contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping method selected. After the shipping label and associated documents are generated, you can retrieve and download them via the Retrieve parcel documents endpoint.
If you have more than one active contracts for a specific carrier, you must fill the contract field with your desired contract ID in your request. You can get your contract ID from the Retrieve a list of contracts endpoint.
International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. You can read more in-depth information on international shipping and its requirements in our developer guides.

​
Multicollo

More information on how to create multiple parcels within one shipment can be found in the Multicollo page of our developer guides.

Authorizations

​
Authorization
string
header
required

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

Headers

​
Sendcloud-Partner-Id
string

If you are an official Sendcloud Tech Partner, send your unique Sendcloud Partner UUID as a request header for the system to recognize you.

The header is not required but if it is set, the system will check it. An unknown or invalid UUID will cause a 400 error.

Query Parameters

​
errors
enum<string>

When making an API request, the errors query parameter can be used to determine the type of errors that should be included in the response. If verbose is specified, the response will only contain errors that Sendcloud has validated. These errors may include shipment details such as invalid addresses or missing postal codes. On the other hand, if verbose-carrier is specified, the response will include errors originating from the carriers side of the shipping process. These errors may result from technical or validation problems, such as connection failures or issues with the carrier`s systems, that prevent the shipment from being processed. More details are described on the page Handling parcel errors.

Available options:
verbose-carrier,
verbose

Body

application/json
​
parcel
Parcel Creation Object · object

Parcel object for a parcel creation

Response

OK

Create a parcel

​
failed_parcels
object[]