> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 (e.g. bicycles, gym stations) or different items purchased together that 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.
## Creating multicollo shipments
Multicollo shipments can be created using the Sendcloud [Shipments API (v3)](/api/v3/shipments) or manually in the Sendcloud platform (learn more in [our help center](https://support.sendcloud.com/hc/en-us/articles/360038716852-How-to-create-multicollo-shipments)).
If you are currently using the legacy Parcels API (v2), see the [migration section below](docs/shipments/multicollo#migrating-from-the-parcels-api-v2-to-the-shipments-api-v3).
Using the Shipments API allows you to provide detailed parcel information such as weight, dimensions, and items for each parcel in the shipment. Providing more accurate parcel details ensures a smoother shipping process, reduces the chance of unexpected carrier surcharges, and may reduce shipping costs depending on your carrier contract and rates.
Some carriers currently support multicollo shipments only via the Sendcloud platform or legacy APIs. See the
[supported carriers](/docs/shipments/multicollo#supported-carriers) section below for details.
## Creating multicollo shipments via the Shipments API
Use the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint to create and announce a multicollo shipment asynchronously.
For each parcel in a multicollo shipment, add a separate object to the `parcels` array in your request.
We recommend providing weight and dimensions info per parcel to avoid potential carrier surcharges.
After creating the shipment:
* Use the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint to check the announcement results
* Use the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint to retrieve the labels
## Supported carriers
Not all carriers support multicollo shipments.
To retrieve shipping options that support multicollo shipments, use the [Shipping options API](/api/v3/shipping-options/create-a-list-of-shipping-options) and make a `POST` request with `{"functionalities": {"multicollo": true}}` in the body.
The response returns shipping options that support multicollo shipments.
Currently international multicollo shipments are only supported in API v3.
Some restrictions apply to multicollo shipments. See our [help
center](https://support.sendcloud.com/hc/en-us/articles/360038716852-How-to-create-multicollo-shipments) for more
information.
## Multicollo labels
The shipping label will reflect the total number of parcels in the consignment and, depending on the carrier, each parcel's position in the shipment (for example: 1/3, 2/3, 3/3).
Each parcel will have a **unique tracking number**, but the customer will only receive **one tracking email** for the entire shipment.
## Avoid being charged for unused multicollo shipments
If you create a shipment using this API but decide not to ship it, you can avoid being charged by using the [Cancel a shipment](/api/v3/shipments/cancel-a-shipment) endpoint. When a multicollo shipment is canceled, all labels from that shipment become canceled.
## Finding the `shipping_option_code`
Make a request to the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint.
The top-level `code` field in each shipping option object is the `shipping_option_code` to be used with the Shipments API. In the example response below, the value `dpd:home` is the `shipping_option_code` used in the `ship_with` field when creating a shipment:
```json Response body theme={null}
{
"data": [
{
"code": "dpd:home", // This is the shipping_option_code
"carrier": {
"code": "dpd",
"name": "DPD"
},
"product": {
"code": "dpd:home",
"name": "DPD Home"
},
"functionalities": {
// ... trimmed for brevity
},
"contract": null,
"weight": {
"min": {
"value": "0.001",
"unit": "kg"
},
"max": {
"value": "31.501",
"unit": "kg"
}
},
"max_dimensions": {
"length": "175.00",
"width": "0.00",
"height": "0.00",
"unit": "cm"
},
"billed_weight": {
"unit": "kg",
"value": "1.320",
"volumetric": false
},
"requirements": {
"fields": [],
"export_documents": false
},
"quotes": null
}
// ... other shipping options
]
}
```
## Migrating from the Parcels API (v2) to the Shipments API (v3)
If you previously created multicollo shipments using the Parcels API (v2), you can migrate to the Shipments API (v3) to benefit from improved multicollo functionality.
Key differences:
* **Parcels API (v2)**: Multicollo shipments were created by specifying the number of parcels in the quantity field.
* **Shipments API (v3)**: Each parcel is defined individually inside the parcels array.
1. Use the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint instead of the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint
2. To find a `shipping_option_code` for use in the `ship_with` field for the Shipments API, you can use the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint
* Also, if you have a direct contract with the carrier, you can add the `contract_id` to the request body (the id can be obtained through the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint)
3. Update your payload to match the expected request body in the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint
* For multicollo, the main change is that instead of specifying a `quantity` when creating a parcel, you can now specify each parcel's details by adding a separate parcel object in the `parcels` array for each parcel in your multicollo shipment.
Providing parcel-specific details (weight, dimensions, items) allows more accurate carrier announcements and improves shipping reliability.