Multicollo

What is multicollo?

Multicollo is a feature that allows sending multiple parcels to be shipped and delivered simultaneously at a higher chance of lower costs by supported carriers. It is handy for merchants who usually send bulky items, for example — bicycles, gym stations, or different items purchased together, but do not fit in one parcel.

In this context, a shipment is a group of parcels that are announced together, and each parcel has its own items and shipping label. All multicollo parcels must be sent from the same sender address to the same destination address.

How does multicollo work at Sendcloud?

We offer three ways to announce multicollo shipments:

  1. Using Shipments V3 API as a recommended option.
  2. Using Parcels V2 API as an alternative option.
  3. Setting it manually from the Sendcloud panel. Learn How to create Multicollo in Help Center.

The new Shipment V3 API has improved multicollo functionality, allowing you to specify weight, dimensions, and items per parcel in a multicollo shipment. Providing more accurate details of the parcels ensures a smoother shipping process, reduces the chance of unexpected carrier surcharges, and might reduce your shipping costs, depending on your carrier contract and rates. Note that we currently support fewer carriers with the Shipments v3 API multicollo compared to Parcels V2 API and the panel

Comparison between Shipment API V3 and Parcel API V2

Shipments V3 API Advantages:

  • Reduces your shipping costs depending on your carrier contract and rates.
  • Ensures a smoother shipping process, because it allows sending more accurate details of the parcels.
  • Reduces the chance of unexpected carrier surcharges.

Parcels V2 API Advantages:

  • Allows you to specify a return shipment in the same endpoint
  • Allows you to create an order on the Sendcloud panel to manually edit it before announcing it

Supported carriers

Not all carriers support multicollo shipments. To check which carriers support multicollo and how to ship with them, refer to the appropriate API version below:

  • API v3: use the Shipping Options V3 API with {“functionalities”: {“multicollo”: true}} POST body. This will return shipping options that support the multicollo functionality.
  • API v2: Use the Shipping products endpoint and make a GET request including the paramater multicollo: true. This will return a list of shipping methods that support multicollo.

Currently international multicollo shipments are only supported in API v3.

Some restrictions apply to multicollo shipments. See our Help Center for more information.

How to announce multicollo shipments

Shipment API V3

Use POST https://panel.sendcloud.sc/api/v3/shipments endpoint to create and announce a multicollo shipment asynchronously. For each parcel in a multicollo shipment, you can provide its details by extending the ‘parcels’ array in your request.

Refer to the endpoint documentation for the description of the required and optional fields. We recommend providing weight and dimensions info per parcel to avoid potential carrier surcharges. You can check the results of the announcement by using the Retrieve a shipment endpoint, and Retrieve a parcel document endpoint for retrieving the labels.

To avoid being charged in case you created a shipment using this API but decided not to ship it, you can use the Cancel a shipment endpoint. When a multicollo shipment is canceled, all labels from that shipment become canceled.

Example request

POST https://panel.sendcloud.sc/api/v3/shipments

  1curl --request POST \
  2   --url https://panel.sendcloud.sc/api/v3/shipments \
  3   --header 'Accept: application/json' \
  4   --header 'Authorization: Basic <credentials>' \
  5   --header 'Content-Type: application/json' \
  6   --data '{
  7      "from_address": {
  8          "address_line_1": "Stadhuisplein 10",
  9          "address_line_2": "2e verdieping",
 10          "city": "Eindhoven",
 11          "company_name": "Sendcloud",
 12          "country_code": "NL",
 13          "email": "marie.doe@sendcloud.com",
 14          "house_number": "10",
 15          "name": "Marie Doe",
 16          "phone_number": "+31612345678",
 17          "postal_code": "5611 EM",
 18          "po_box": "PO Box 678"
 19      },
 20      "to_address": {
 21          "address_line_1": "Stadhuisplein 10",
 22          "address_line_2": "2e verdieping",
 23          "city": "Rotterdam",
 24          "company_name": "Sendcloud",
 25          "country_code": "NL",
 26          "email": "marie.doe@sendcloud.com",
 27          "house_number": "10",
 28          "name": "Marie Doe",
 29          "phone_number": "+31612345678",
 30          "postal_code": "3029 AD",
 31          "po_box": "PO Box 679"
 32      },
 33      "ship_with": {
 34          "type": "shipping_option_code",
 35          "properties": {
 36              "shipping_option_code": "dpd:home"
 37          }
 38      },
 39      "order_number": "1234567890",
 40      "total_order_price": {
 41          "currency": "EUR",
 42          "value": "11.11"
 43      },
 44      "parcels": [
 45          {
 46              "dimensions": {
 47                  "length": "5.00",
 48                  "width": "15.00",
 49                  "height": "20.00",
 50                  "unit": "cm"
 51              },
 52              "weight": {
 53                  "value": "1.320",
 54                  "unit": "kg"
 55              },
 56              "parcel_items": [
 57                  {
 58                      "item_id": "5552",
 59                      "description": "T-Shirt XL",
 60                      "quantity": 1,
 61                      "weight": {
 62                          "value": 0.3,
 63                          "unit": "kg"
 64                      },
 65                      "price": {
 66                          "value": 10.65,
 67                          "currency": "EUR"
 68                      },
 69                      "hs_code": "12345678",
 70                      "origin_country": "NL",
 71                      "sku": "TS1234",
 72                      "product_id": "19284",
 73                      "mid_code": "NLOZR92MEL",
 74                      "material_content": "100% Cotton",
 75                      "intended_use": "Personal use",
 76                      "properties": {
 77                          "size": "XL",
 78                          "color": "green"
 79                      }
 80                  }
 81              ]
 82          },
 83          {
 84              "dimensions": {
 85                  "length": "10.00",
 86                  "width": "20.00",
 87                  "height": "30.00",
 88                  "unit": "cm"
 89              },
 90              "weight": {
 91                  "value": "2.320",
 92                  "unit": "kg"
 93              },
 94              "parcel_items": [
 95                  {
 96                      "item_id": "5552",
 97                      "description": "T-Shirt L",
 98                      "quantity": 1,
 99                      "weight": {
100                          "value": 0.3,
101                          "unit": "kg"
102                      },
103                      "price": {
104                          "value": 7.65,
105                          "currency": "EUR"
106                      },
107                      "hs_code": "12345677",
108                      "origin_country": "NL",
109                      "sku": "TS1235",
110                      "product_id": "19284",
111                      "mid_code": "NLOZR92MEL",
112                      "material_content": "100% Cotton",
113                      "intended_use": "Personal use",
114                      "properties": {
115                          "size": "XL",
116                          "color": "green"
117                      }
118                  }
119              ]
120          }
121      ]
122   }'

Parcel API V2

To create a multicollo, include the number of parcels you wish to ship in the quantity field under the parcel object and make a POST request to the Create multiple parcels endpoint. The maximum number of parcels you can create under quantity is 20.

  • If the value of request_label is true, then the parcels will be announced together, and the response will include the URL to download each shipping label.
  • If the value of request_label is false, the parcel object will be created with a quantity matching the value you specified in your request. The parcel will appear in the Incoming order overview of the Sendcloud panel with the status Ready to process. When the parcel is processed, the correct number of shipping labels will be created.

Example request

POST https://panel.sendcloud.sc/api/v2/parcels

 1curl --location -g --request POST 'https://panel.sendcloud.sc/api/v2/parcels' \
 2   --header 'Authorization: Basic <credentials>' \
 3   --header 'Accept: application/json' \
 4   --header 'Content-Type: application/json' \
 5   --data '{
 6       "parcels": [
 7           {
 8               "name": "John Doe",
 9               "company_name": "Sendcloud",
10               "address": "Insulindelaan",
11               "house_number": "115",
12               "city": "Eindhoven",
13               "postal_code": "5642CV",
14               "telephone": "+31612345678",
15               "email": "john@doe.com",
16               "data": [],
17               "country": "NL",
18               "shipment": {
19                   "id": 4203
20               },
21               "weight": "10.000",
22               "order_number": "1",
23               "insured_value": 0,
24               "total_order_value": "11.11",
25               "total_order_value_currency": "EUR",
26               "quantity": 3,
27               "request_label": true
28           }
29       ]
30   }'

Multicollo labels

The shipping label will reflect the total number of parcels in the consignment, and, depending on the carrier, each parcel’s position, for example — packages 1/3, 2/3, 3/3, etc. Each parcel will have a unique tracking number, but the customer will only receive one tracking email for all of the parcels in the consignment.

Labels can be printed directly from the Sendcloud panel, or you can request them via the Retrieve a parcel document endpoint by including the id of each parcel contained in the collo in your request.

Migrating from Parcels V2 API to Shipments V3 API

If you use the old Parcels V2 API for multicollo shipments and want to migrate to the Shipment API v3 to benefit from the improved multicollo functionality:

  1. Use https://panel.sendcloud.sc/api/v3/shipments endpoint instead of https://panel.sendcloud.sc/api/v2/parcels;
  2. To specify the shipping_option_code, you can use the Create a list of shipping options endpoint, as mentioned in the APPENDIX at the end of this documentation. Also, if you have a direct contract with the carrier, you can specify the contract_id in the https://panel.sendcloud.sc/api/v3/shipments endpoint request (the id can be obtained through the Retrieve a list of contracts endpoint);
  3. Update your payload as described in the How to announce multicollo shipments section above. In short, instead of specifying quantity in the parcels object, you can now specify each parcel’s details by providing additional objects in the parcels list for each parcel in your multicollo shipment. Refer to the following example request and response:

Request example

 1curl --location -g --request POST 'https://panel.sendcloud.sc/api/v3/fetch-shipping-options' \
 2   --header 'Authorization: Basic <credentials>' \
 3   --header 'Accept: application/json' \
 4   --header 'Content-Type: application/json' \
 5   --data '{
 6       "from_country": "NL",
 7       "to_country": "NL",
 8       "from_postal_code": "5611 GE",
 9       "to_postal_code": "3029 AD",
10       "weight": {
11           "value": "1.320",
12           "unit": "kg"
13       },
14       "carrier": "dpd",
15       "functionalities": {
16           "multicollo": true
17       }
18   }'

Response example

The shipping_option_code represents the main code in the response below (first one in the JSON object), in this case, "dpd:home".

Note that only one shipping option is shown below because the response is too long for an example, but you can expect a bigger response.

 1{
 2 "data": [
 3   {
 4     "code": "dpd:home",
 5     "carrier": {
 6       "code": "dpd",
 7       "name": "DPD"
 8     },
 9     "product": {
10       "code": "dpd:home",
11       "name": "DPD Home"
12     },
13     "functionalities": {
14       "b2b": false,
15       "b2c": true,
16       "ers": false,
17       "size": null,
18       "tyres": false,
19       "sorted": false,
20       "boxable": false,
21       "premium": false,
22       "returns": false,
23       "segment": null,
24       "tracked": true,
25       "id_check": false,
26       "incoterm": null,
27       "manually": false,
28       "priority": null,
29       "age_check": null,
30       "insurance": 520,
31       "labelless": false,
32       "last_mile": "home_delivery",
33       "signature": true,
34       "surcharge": false,
35       "first_mile": "pickup",
36       "multicollo": true,
37       "bulky_goods": false,
38       "form_factor": "parcel",
39       "fresh_goods": false,
40       "eco_delivery": false,
41       "service_area": "domestic",
42       "flex_delivery": false,
43       "fragile_goods": false,
44       "non_conveyable": false,
45       "dangerous_goods": false,
46       "delivery_before": null,
47       "cash_on_delivery": null,
48       "harmonized_label": false,
49       "weekend_delivery": null,
50       "carrier_insurance": false,
51       "delivery_attempts": 1,
52       "delivery_deadline": "best_effort",
53       "neighbor_delivery": true,
54       "customs_value_limit": null,
55       "registered_delivery": false,
56       "carrier_billing_type": null,
57       "personalized_delivery": false
58     },
59     "contract": null,
60     "weight": {
61       "min": {
62         "value": "0.001",
63         "unit": "kg"
64       },
65       "max": {
66         "value": "31.501",
67         "unit": "kg"
68       }
69     },
70     "max_dimensions": {
71       "length": "175.00",
72       "width": "0.00",
73       "height": "0.00",
74       "unit": "cm"
75     },
76     "billed_weight": {
77       "unit": "kg",
78       "value": "1.320",
79       "volumetric": false
80     },
81     "requirements": {
82       "fields": [],
83       "export_documents": false
84     },
85     "quotes": null
86   }
87 ]
88}

On this page

Go to top