Skip to main content
Sendcloud’s flexible shipping API covers every part of the shipping process, from label creation right up to the point of delivery. Ready to put your shipping processes on autopilot? Read on to learn how to create your first parcel with Sendcloud’s Shipping API. There are two ways to create a parcel via the API: Method 1: Create a parcel object
  • This is the most flexible means of creating a parcel. The parcel object is created in the Sendcloud system, but the parcel is not immediately announced with the carrier.
  • This gives you time to continue making changes to the parcel data and decide on a shipping method right up until the moment you’re ready to create the label.
  • Parcels can be processed either via the Sendcloud panel, or you can perform all interactions via the API, depending on your specific use case.
Method 2: (Advanced option): Create the parcel and shipping label in a single API call
  • This method is described in more detail at the end of this tutorial.
To help get you started, this guide will cover the basics of creating a parcel via the API, step-by-step. Once the parcel is created, you can continue on to the next steps to learn how to choose a shipping method and print the label.

​
Before you begin

  1. Make sure you’ve completed basic account set up. See Quickstart
  2. You’ll need to have obtained your API keys so you can authenticate with our API. See Authentication
  3. You’ll need access to a tool that allows you to make API calls. Examples are Postman and Insomnia.

​
The Create a parcel or parcels API endpoint

Parcels are created by sending a HTTP POST request to the Create a parcel or parcels endpoint.
Request method and URL
POST https://panel.sendcloud.sc/api/v2/parcels

​
Authorization header

Every time you make an API call, you need to authenticate your connection to Sendcloud by including your API keys through a HTTP header.
Authorization header
Authorization: Basic <credentials>

​
Step 1: Prepare your request

In the body of your HTTP request, you need to specify all the required information for the shipping label. Below you can find an example which will create a parcel object in your Sendcloud account.
Example request body
{
  "parcel": {
    "name": "John Doe",
    "company_name": "FlowerShop",
    "email": "john@doe.com",
    "telephone": "+31611223344",
    "address": "Fürstenrieder Str.",
    "house_number": "70",
    "address_2": "",
    "city": "Munich",
    "country": "DE",
    "postal_code": "80686",
    "country_state": null,
    "to_service_point": 10168633,
    "to_post_number": 262373726,
    "customs_invoice_nr": "",
    "customs_shipment_type": null,
    "parcel_items": [
      {
        "description": "T-Shirt",
        "hs_code": "6109",
        "origin_country": "SE",
        "product_id": "898678671",
        "properties": {
          "color": "Blue",
          "size": "Medium"
        },
        "quantity": 2,
        "sku": "TST-OD2019-B620",
        "value": "19.95",
        "weight": "0.9"
      },
      {
        "description": "Laptop",
        "hs_code": "84713010",
        "origin_country": "DE",
        "product_id": "5756464758",
        "properties": {
          "color": "Black",
          "internal_storage": "2TB"
        },
        "quantity": 1,
        "sku": "LT-PN2020-B23",
        "value": "876.97",
        "weight": "1.69"
      }
    ],
    "weight": "3.49",
    "length": "31.5",
    "width": "27.2",
    "height": "12.7",
    "total_order_value": "896.92",
    "total_order_value_currency": "EUR",
    "shipment": {
      "id": 1316,
      "name": "DHL Parcel Connect 2-5kg to ParcelShop"
    },
    "shipping_method_checkout_name": "Battery WarehouseX DHL",
    "sender_address": 1,
    "quantity": 1,
    "total_insured_value": 0,
    "is_return": false,
    "request_label": false,
    "apply_shipping_rules": false,
    "request_label_async": false
  }
}
The important thing to note here is that the request_label parameter is set to false. This allows you to create a parcel without announcing it to a carrier or creating a shipping label.
The parcel will be created using the default shipping method you saved in your account, and can be updated later. Also note that specific carriers might impose additional requirements on address-related fields.

​
Other request fields

There are many other additional fields that you can specify when creating a parcel. An example would be the sender_address parameter which lets you ship a parcel from a different sender location, or the parameters related to customs information for international shipping. You can find a list of the supported fields in our API reference.

​
Step 2: Send your request

Take the example above, and use it to make a POST request to http://panel.sendcloud.sc/api/v2/parcels.
Request method, URL, and Authorization header
POST https://panel.sendcloud.sc/api/v2/parcels
Authorization: Basic <base64-encoded-token>
If everything went well, you’ll receive a HTTP 200 status code and a parcel object in the response body. See an example of the response body in the API reference.

​
Some things to note about the response

  • The newly-created parcel will be assigned a parcel id, e.g. "id": 189169249. This is the unique parcel identifier which we will use whenever we want to update a parcel or create the label via the API.
  • The current status of the newly-created parcel will be "No label". It will appear in the Sendcloud panel under the Incoming order view with the message Ready to process until we create a label for it. Screenshot of the Incoming order view, showing the newly-created parcel with the status "Ready to process"

​
Step 3: Create the shipping label

To create shipping labels via the API, you need to use the Update a parcel endpoint to update the value of request_label to true. Via this endpoint, you can also make changes to any of the properties that can be used for creating a parcel.

​
Generating a label for an existing parcel

In this example, we will update parcel "id": 1 as follows:
  • Create the shipping label by providing the data "request_label": true
  • Change the name of the recipient to a new value
  • Change the shipping method by providing the corresponding id. In this example, we’ll be using the method “Unstamped letter” to create a test label.
You’ll be invoiced for any shipping labels you create if you don’t cancel or delete them within the cancellation deadline. You can create test labels without receiving a charge by using the shipping method Unstamped letter ("id": 8)
Request method, URL, and Authorization header
PUT https://panel.sendcloud.sc/api/v2/parcels
Authorization: Basic <base64-encoded-token>
Example request body
{
  "parcel": {
    "id": 1,
    "request_label": true,
    "name": "Mr Test",
    "shipment": {
      "id": 8,
      "name": "Unstamped letter"
    }
  }
}
Once you’ve prepared the response body, make a PUT request to the Update a parcel endpoint. Make sure to include your authentication and content headers, as you did in Step 2. If everything goes well, you should receive a response similar to the one below:
Example response body
{
  "parcel": {
    "id": 1,
    "name": "Mr Test",
    "shipment": {
      "id": 8,
      "name": "Unstamped letter"
    },
    "status": {
      "id": 1000,
      "message": "Ready to send"
    },
    "label": {
      "normal_printer": [
        "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0",
        "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=1",
        "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=2",
        "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=3"
      ],
      "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/1"
    },
    "shipping_method": 8
    // ... other parcel data
  }
}
Notice that the response reflects the updates you have made to the customer name, and that the parcel status is now “Ready to send”. The shipping method has been updated to “Unstamped letter”.

​
Step 4: Download the shipping label

At the end of the previous step, you should have received a response which contains some URLs under the label field. These URLs are your links to download the shipping label. Labels can be downloaded in PDF format and are provided in A4 size for normal printers, and A6 size for label printers. Under normal_printer, the start_from value indicates the position of the label on an A4 size page:
  • 0 = Top left
  • 1 = Top right
  • 2 = Bottom left
  • 3 = Bottom right
You’ll need to provide your API credentials again to access the link to download your labels. You can do this by making a GET request to the URL of the label you want to access, and including the Authorization header.
Request method, URL, and Authorization header
GET https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0
Authorization: Basic <base64-encoded-token>
Labels can also be downloaded in bulk directly from the Sendcloud panel under the Created labels tab, or via the Retrieve multiple PDF labels and Bulk PDF label printing endpoints.
Congrats! You’ve just created your first parcel and downloaded the shipping label via the API.

​
Next steps

You can continue reading more tutorials or dive directly into exploring our API references.
  • Choose a shipping method - learn how to retrieve the full list of shipping services available to you via Sendcloud
  • Tracking parcels - to see how you can track the delivery journey of your newly created parcel as it travels to your customer
  • Create a return - read how you can create a return parcel shipment using the Sendcloud Returns API
  • API v2 reference and API v3 reference - browse our API references to explore more options for creating parcels and managing your shipping processes.

​
Advanced options

​
Create a parcel and immediately request a label in a single API call

If you already know which shipping method you want to use to send your parcel, you can bypass Step 3 above by making a POST request to the Create a parcel or parcels endpoint, including "request_label": "true".
When directly announcing parcels in this way, the shipment field is mandatory, and a shipping method id and name must be provided in the API request. If you’re shipping parcels internationally, pay attention to the additional fields which become mandatory for customs documentations purposes. A full list of required parameters can be found in the API reference.

​
Create a return parcel

You can use the Create a parcel or parcels endpoint to create return labels via the API. The process for creating a return label via this method is the same as for creating a parcel, but you must set the value of the is_return property to true and specify the customer’s address address in the from_* fields. It’s important to note that standard shipping methods don’t apply to return parcels. You can find an overview of available return methods via the List of all shipping methods endpoint and include the parameter "is_return": true.
You can also create returns using the Returns API by following the Create a return guide.

​
Ship parcels and retrieve methods for your sender addresses based in other countries

You can set up multiple sender addresses in your Sendcloud account, and specify which sender address you want to ship from when you create a parcel. See our sender addresses documentation for more info.

​
Automatically apply your preferred shipping methods via shipping rules

Shipping rules are a Sendcloud feature which can be used in conjunction with the API to take the legwork out of manually choosing and selecting the best method for your created parcels. See our shipping rules documentation for more details. You can customize a brand in your Sendcloud account to make use of handy marketing tools, such as customizable tracking notifications and branded return portals for each of your integrations. See more about creating your brand in our help center.

​
Receive real time parcel status updates via Webhooks

Actively receive updates regarding parcel events directly to your application by configuring Webhooks.