Create a shipment with rules and/or defaults and announce it synchronously
Create and announce a shipment applying shipping rules and/or defaults
Headers
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.
Request body
Example request
{
"brand_id": 42,
"ship_with": {
"type": "shipping_option_code",
"properties": {
"shipping_option_code": "postnl:standard/insured=3000",
"contract_id": 517
}
},
"to_address": {
"name": "John Doe",
"company_name": "Sendcloud",
"address_line_1": "Stadhuisplein",
"house_number": "50",
"address_line_2": "Apartment 17B",
"postal_code": "1013 AB",
"city": "Eindhoven",
"state_province_code": "IT-RM",
"country_code": "NL",
"email": "johndoe@gmail.com",
"phone_number": "+319881729999"
},
"total_order_price": {
"value": "12.65",
"currency": "USD"
},
"reference": "shipment-1234",
"external_reference_id": "unique-value-1234",
"validation_methods": [
"here"
],
"carrier_fields": {
"hide_sender": true
},
"from_address": {
"sender_address_id": 192
},
"customs_information": {
"invoice_number": "INV-123",
"export_reason": "commercial_goods",
"export_type": "private",
"invoice_date": "2023-08-24",
"discount_granted": {
"value": "14.99",
"currency": "EUR"
},
"freight_costs": null,
"insurance_costs": {
"value": "3.60",
"currency": "EUR"
},
"other_costs": {
"value": "1.2",
"currency": "EUR"
},
"goods_description": "Electronic components and accessories",
"general_notes": "Compliance: Goods comply with international safety standards (CE certified).",
"additional_declaration_statements": [
"With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention.",
"I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable."
],
"importer_of_record": {
"name": "John Doe",
"company_name": "ImporterCo",
"address_line_1": "Maple Avenue",
"house_number": "123",
"postal_code": "90210",
"city": "Springfield",
"country_code": "US",
"state_province_code": "US-MA",
"telephone": "+15551234567",
"email": "info@importer-of-record-example.com"
},
"tax_numbers": {
"sender": [
{
"name": "VAT",
"country_code": "NL",
"value": "NL123456789B01"
},
{
"name": "EORI",
"country_code": "NL",
"value": "NL123456789"
}
],
"receiver": [
{
"name": "EIN",
"country_code": "US",
"value": "123456789"
}
],
"importer_of_record": [
{
"name": "EIN",
"country_code": "US",
"value": "987654321"
}
]
}
},
"to_service_point": {
"id": "123"
},
"label_details": {
"mime_type": "application/zpl",
"dpi": 300
},
"delivery_dates": {
"handover_at": "2025-02-27T10:00:00.555309+00:00",
"deliver_at": "2025-03-15T10:00:00.555309+00:00",
"earliest_delivery_time": "09:00",
"latest_delivery_time": "17:00"
},
"parcels": [
{
"dimensions": {
"length": "15",
"width": "20.5",
"height": "37",
"unit": "mm"
},
"weight": {
"value": "14.5",
"unit": "g"
},
"additional_insured_price": {
"value": "12.65",
"currency": "USD"
},
"label_notes": [
"The doorbell isn’t working"
],
"sscc": "019844628346512933",
"package_type": "package",
"carrier_fields": {
"collo_barcode": "ABC123"
},
"parcel_items": [
{
"item_id": "5552",
"description": "T-Shirt XL",
"quantity": 1,
"weight": {
"value": 14.5,
"unit": "g"
},
"price": {
"value": "12.65",
"currency": "USD"
},
"hs_code": "620520",
"origin_country": "NL",
"sku": "TS1234",
"product_id": "19284",
"mid_code": "NLOZR92MEL",
"material_content": "100% Cotton",
"intended_use": "Personal use",
"dds_reference": "25FIYPEK0A7573",
"taric_doc_code": "Y142",
"manufacturer_product_id": "ABC-12345",
"manufacturer_product_id_std": "01234567890128",
"properties": {
"size": "red",
"color": "green"
}
}
]
}
],
"apply_shipping_defaults": true,
"apply_shipping_rules": true,
"delivery_indicator": "DHL home delivery"
}Response
Shipment response
Changes
Changed in 3 of the 5 revisions of this API.29
- ▲
added
dhl-freight-shipment-extrasto theallOf[subschema #1: Base shipment response Object]/allOf[subschema #1: Shipment common Object]/allOf[subschema #1: Shipment common with optional fields Object]/carrier_fieldsresponse propertyoneOflist for the response status409response-property-one-of-added
- ▲
added
dhl-freight-shipment-extrasto thedata/allOf[subschema #1: Base shipment response Object]/allOf[subschema #1: Shipment common Object]/allOf[subschema #1: Shipment common with optional fields Object]/carrier_fieldsresponse propertyoneOflist for the response status201response-property-one-of-added
- ○
added
dhl-freight-shipment-extrasto theallOf[subschema #1: Shipment request with optional fields Object]/allOf[subschema #1: Shipment common with optional fields Object]/carrier_fieldsrequest propertyoneOflistrequest-property-one-of-added
- ▲
- ○
added the new optional request property
allOf[subschema #1: Shipment request with optional fields Object]/allOf[subschema #4]/delivery_dates/oneOf[subschema #1: Delivery Dates]/earliest_delivery_timenew-optional-request-property
- ○
added the new optional request property
allOf[subschema #1: Shipment request with optional fields Object]/allOf[subschema #4]/delivery_dates/oneOf[subschema #1: Delivery Dates]/latest_delivery_timenew-optional-request-property
- ○
added the optional property
allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/earliest_delivery_timeto the response with the409statusresponse-optional-property-added
- ○
added the optional property
allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/latest_delivery_timeto the response with the409statusresponse-optional-property-added
- ○
added the optional property
data/allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/earliest_delivery_timeto the response with the201statusresponse-optional-property-added
- ○
added the optional property
data/allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/latest_delivery_timeto the response with the201statusresponse-optional-property-added
- ○
- ○
added the optional property
allOf[subschema #2]/parcels/items/allOf[subschema #1: Parcels Array Response Object]/allOf[subschema #2]/tracking_numbersto the response with the409statusresponse-optional-property-added
- ○
added the optional property
data/allOf[subschema #2]/parcels/items/allOf[subschema #1: Parcels Array Response Object]/allOf[subschema #2]/tracking_numbersto the response with the201statusresponse-optional-property-added
- ○