> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a shipment
Shipments can be created using the Sendcloud [Shipments API](/api/v3/shipments) in two different ways:
* **Synchronous**: You receive the carrier announcement result immediately. Best suited for small batches or testing flows.
* **Asynchronous**: You receive a shipment object right away, but must poll another endpoint to know if the carrier successfully processed it. Recommended for production-scale or multi-parcel flows.
You’ll be invoiced for any shipments you create if you don’t cancel them within the [cancellation
deadline](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment). You can create
[test labels](/docs/getting-started/creating-test-labels) without receiving a charge by using the shipping option
Unstamped letter (`"shipping_option_code": "sendcloud:letter"`) see the [Cancel a shipment
page](docs/shipments/cancel-a-shipment) for more details.
## Synchronous announcement
Use the synchronous endpoint when you need immediate feedback on whether the shipment was successfully announced to the carrier (for example, when shipping single parcels or low volumes).
| Key details | |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Endpoint** | [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) |
| **Max parcels per shipment** | **15** |
| **Response** | Includes full shipment and parcel data, current shipment status, and any carrier errors returned during announcement. |
## Asynchronous announcement
Use the asynchronous endpoint for most production flows, especially when dealing with higher volumes or multicollo (multi-parcel) shipments.
| Key details | |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Endpoint | [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) |
| Max parcels per shipment | **50** (note: carrier-specific limits may be lower) |
| Response | Includes shipment and parcel data but no confirmation of whether it was successfully announced to the carrier. |
| To check shipment status | Use the [Retrieve shipments](/api/v3/shipments/retrieve-shipments) endpoint to retrieve the announcement result and any possible carrier errors. |
## Request example
Below is a minimal JSON example required to create a shipment - valid for both synchronous and asynchronous endpoints.
```json Example request body theme={null}
{
"to_address": {
"name": "John Doe",
"company_name": "Sendcloud",
"address_line_1": "Insulindelaan 115",
"house_number": "115",
"postal_code": "5642CV",
"city": "Eindhoven",
"country_code": "NL",
"phone_number": "+31612345678",
"email": "john.doe@sendcloud.com",
"po_box": "PO Box 678"
},
"from_address": {
"name": "Marie Doe",
"company_name": "Sendcloud",
"address_line_1": "Stadhuisplein 10",
"address_line_2": "2e verdieping",
"house_number": "10",
"postal_code": "5611 EM",
"city": "Eindhoven",
"country_code": "NL",
"phone_number": "+31612345678",
"email": "marie.doe@sendcloud.com",
"po_box": "PO Box 478"
},
"ship_with": {
"type": "shipping_option_code",
"properties": {
"shipping_option_code": "postnl:standard",
"contract_id": 517
}
},
"parcels": [
{
"weight": {
"value": "1.320",
"unit": "kg"
}
}
]
}
```
A typical shipment includes:
* Sender and recipient addresses
* A `shipping_option_code` and contract
* One or more parcels with weight
* Optional fields: parcel dimensions, items, insurance, customs details, or branding
Note: Some carriers calculate shipping costs based on volumetric weight rather than actual weight. Volumetric weight
is typically calculated using the formula (W × L × H)/divisor, where the divisor is defined in your agreement with the
carrier or with Sendcloud. For shipments using a `shipping_option_code` associated with these carriers, parcel
dimensions must be provided in addition to weight.
If the request is successful, you'll receive:
* HTTP 200 status code
* A shipment object in the response body
See the API reference response example for full schema details.
A successful response includes:
* `id`: The unique shipment ID (e.g. `"id": 189169249`), used for retrieving shipment data later.
* `parcels[]`: List of associated parcel objects, each with its own parcel ID used to fetch documents like labels or customs forms.
* `label_file` and carrier announcement results/errors (for synchronous announcements only).
* Shipments that have been successfully announced to the carrier start with the status “Ready to Send.” You can view these shipments and their associated parcels in the Sendcloud panel under the Created Labels tab.
## Error Handling
Synchronous shipment creation endpoints may return an HTTP 200 status code even if the carrier announcement fails. Always inspect the response's `errors` object for issues and verify the `shipment.status` field. A status of "Announcement Failed" confirms the carrier announcement did not succeed.
For carrier-related failures after an HTTP 200, create a new shipment request to resolve the issue. **Shipments in "Announcement Failed" status incur no charges**.
See the API reference for full error response details for the:
* [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously)
* [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously)
## Advanced Options
Now that you’ve mastered the basics of creating a shipment, it’s time to uncover the full potential of our Shipments API. Explore the features below to help you automate, customise, and scale your shipping operations with ease:
* Shipping rules and defaults: Save time by automating your shipping preferences. Set rules to automatically select shipping options, insurance amounts, or default order values based on a set of conditions.
* Multicollo (Multiple parcels): Got an oversized order that won’t fit in one box? No problem! Create shipments with multiple parcels and track them all under a single master tracking number.
* Shipment protection: Safeguard your deliveries against loss, theft, or damage with Sendcloud Shipment Protection. If something goes wrong, you can easily request a refund for your items.
* International shipping: Sending orders across borders? We’ll take care of customs requirements for you. Generate the necessary documentation automatically, no extra hassle required.