Skip to main content
POST
/
shipments
/
announce
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/shipments/announce \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "label_details": {
    "mime_type": "application/pdf",
    "dpi": 72
  },
  "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
    }
  },
  "order_number": "1234567890",
  "total_order_price": {
    "currency": "EUR",
    "value": "11.11"
  },
  "parcels": [
    {
      "dimensions": {
        "length": "5.00",
        "width": "15.00",
        "height": "20.00",
        "unit": "cm"
      },
      "weight": {
        "value": "1.320",
        "unit": "kg"
      },
      "label_notes": [
        "I live at the blue door",
        "The doorbell isn't working"
      ],
      "parcel_items": [
        {
          "item_id": "5552",
          "description": "T-Shirt XL",
          "quantity": 1,
          "weight": {
            "value": 0.3,
            "unit": "kg"
          },
          "price": {
            "value": "12.65",
            "currency": "EUR"
          },
          "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": "XL",
            "color": "green"
          }
        },
        {
          "item_id": "98712",
          "description": "Sneakers 42",
          "quantity": 1,
          "weight": {
            "value": 1.02,
            "unit": "kg"
          },
          "price": {
            "value": "12.65",
            "currency": "EUR"
          },
          "hs_code": "620520",
          "origin_country": "US",
          "sku": "TS1234",
          "product_id": "19284",
          "mid_code": "US1234567",
          "material_content": "100% Cotton",
          "intended_use": "Personal use",
          "dds_reference": "25FIYPEK0A7573",
          "taric_doc_code": "Y142",
          "properties": {
            "size": 42,
            "color": "black"
          }
        }
      ]
    }
  ]
}
EOF
{
  "data": {
    "id": "XXX-Shipment-id",
    "label_details": {
      "mime_type": "application/pdf",
      "dpi": 72
    },
    "order_number": "1234567890",
    "total_order_price": {
      "currency": "EUR",
      "value": "11.11"
    },
    "parcels": [
      {
        "id": 383707309,
        "status": {
          "code": "READY_TO_SEND",
          "message": "Ready to send"
        },
        "documents": [
          {
            "type": "label",
            "size": "a6",
            "link": "https://panel.sendcloud.sc/api/v3/parcels/383707309/documents/label"
          }
        ],
        "dimensions": {
          "width": "15.00",
          "length": "5.00",
          "height": "20.00",
          "unit": "cm"
        },
        "weight": {
          "value": "1.320",
          "unit": "kg"
        },
        "tracking_url": "https://tracking.eu-central-1-0.sendcloud.sc/forward?carrier=postnl&code=3SYZXG8498635&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642+CV&servicepoint_verification=&created_at=2024-06-06",
        "tracking_number": "3SYZXG8498635",
        "additional_carrier_data": {
          "awb_tracking_number": null,
          "box_number": null
        },
        "created_at": "2024-06-06T17:11:14.616615Z",
        "updated_at": "2024-06-06T17:11:14.648081Z",
        "announced_at": "2024-06-06T17:11:14.712398Z",
        "label_notes": [
          "I live at the blue door",
          "The doorbell isn't working"
        ],
        "package_type": "package",
        "parcel_items": [
          {
            "item_id": "5552",
            "description": "T-Shirt XL",
            "quantity": 1,
            "weight": {
              "value": 0.3,
              "unit": "kg"
            },
            "price": {
              "value": "12.65",
              "currency": "EUR"
            },
            "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": null,
            "manufacturer_product_id_std": "09876543210987",
            "properties": {
              "size": "XL",
              "color": "green"
            }
          },
          {
            "item_id": "98712",
            "description": "Sneakers 42",
            "quantity": 1,
            "weight": {
              "value": 1.02,
              "unit": "kg"
            },
            "price": {
              "value": "12.65",
              "currency": "EUR"
            },
            "hs_code": "620520",
            "origin_country": "US",
            "sku": "TS1234",
            "product_id": "19284",
            "mid_code": "US1234567",
            "material_content": "100% Cotton",
            "intended_use": "Personal use",
            "dds_reference": "25FIYPEK0A7573",
            "taric_doc_code": "Y142",
            "properties": {
              "size": 42,
              "color": "black"
            }
          }
        ]
      }
    ],
    "from_address": {
      "address_line_1": "Stadhuisplein 10",
      "address_line_2": "2e verdieping",
      "city": "Eindhoven",
      "company_name": "Sendcloud",
      "country_code": "NL",
      "email": "marie.doe@sendcloud.com",
      "house_number": "10",
      "name": "Marie Doe",
      "phone_number": "+31612345678",
      "postal_code": "5611 EM",
      "po_box": "PO Box 678"
    },
    "to_address": {
      "address_line_1": "Insulindelaan",
      "address_line_2": "",
      "city": "Eindhoven",
      "company_name": "Sendcloud",
      "country_code": "NL",
      "email": "john.doe@sendcloud.com",
      "house_number": "115",
      "name": "John Doe",
      "phone_number": "+31612345678",
      "postal_code": "5642 CV",
      "po_box": "PO Box 483"
    },
    "ship_with": {
      "type": "shipping_option_code",
      "properties": {
        "shipping_option_code": "postnl:standard",
        "contract_id": 517
      }
    },
    "customs_information": null,
    "carrier": {
      "code": "postnl",
      "name": "PostNL"
    },
    "errors": []
  }
}

​
International shipments

If you want to create a shipment to be sent to a destination country outside the EU, it’s mandatory to include additional information related to the shipment contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping option selected. After the shipping label and associated documents are generated, you can retrieve and download them via the Retrieve a parcel document endpoint. Note that when passing along prices, mixed currencies are not accepted. Therefore, ensure that all price fields use the same currency.

Authorizations

​
Authorization
string
header
required

Basic Authentication using API key and secrets is currently the main authentication mechanism.

Headers

​
Sendcloud-Partner-Id
string

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.

Body

application/json

Synchronous Announcement Shipment request object model

​
ship_with
Ship with object · object
required

The ship with object can be used to define how you would like to send your shipment.

You can use a shipping_option_code. This is a unique identifier that displays what carrier and what set of shipping functionalities you want to use.

Example:
{
  "type": "shipping_option_code",
  "properties": {
    "shipping_option_code": "postnl:standard/insured=3000",
    "contract_id": 517
  }
}
​
to_address
Address Object · object
required

Sendcloud Address object

​
from_address
Sender Address ID · object
required

The sender address for the shipment. You can either provide a sender_address_id to reference a pre-configured sender address (with optional address field overrides), or provide all address fields directly.

​
parcels
Parcel common Object · object[]
required

Represents each package of the shipment. Note that you can send a maximum of 15 parcels per shipment to this endpoint.

To announce more than 15 parcels in the same shipment, you can use the Create and announce a shipment asynchronously endpoint.

Note: each carrier can have a lower than the default number of parcels limit per shipment.

Required array length: 1 - 15 elements
​
brand_id
integer

The id of the brand. Brands can be added through the Sendcloud platform and be retrieved (alongside their id) from the Retrieve a list of brands endpoint.

Example:

42

​
order_number
string

Order number generated manually or by shop system

​
total_order_price
Price object · object

Price, consisting of a value and currency.

​
reference
string | null

A reference that will be stored on the Shipment and returned in your responses. This is not sent to the carrier.

Example:

"shipment-1234"

​
external_reference_id
string | null

An optional reference can be provided by the API user; if included, it must be unique across shipments of the user. Using the same reference more than once will result in a 409 HTTP status code and the associated object being returned.

Example:

"unique-value-1234"

​
validation_methods
enum<string>[]

A list of additional address validations to apply. At present, the only supported validation service is Here, and it is used exclusively for transactional contracts. To enable this feature, contract_id must be explicitly set and must reference a transactional contract.

When using the "Here" validation method, Sendcloud will attempt to verify and correct the provided address based on the best available match from the selected provider. For example, if you submit "city": "Amstredan", the system will automatically correct it to "city": "Amsterdam".

If no suitable match is found, the request will return an error.

Please note that only address components recognised by the selected provider will be kept. Any additional details included in address fields (e.g. "address_line_2": "Ring the blue doorbell") will be removed if they do not match the provider records.

For adding delivery notes or extra instructions, use the parcels.label_notes field instead.

Available options:
here
Example:
["here"]
​
carrier_fields
Default · object

Optional carrier-specific shipment-level fields. The accepted shape depends on the carrier resolved from ship_with.

​
customs_information
CustomsInformation · object

Optional customs information that should be provided for international shipments. This information is used for generating customs documents.

Example:
{
  "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
Sendcloud ID · object

Node for service point information. Use the Retrieve a list of service points endpoint to find service points, or pass in the carrier's id for the service point.

If both the id and carrier_service_point_id are provided, the carrier_service_point_id will be prioritised.

​
label_details
Label details Object · object

Describes the format and resolution of the label.

Note: If you request a label in ZPL format and the carrier supports native ZPL, then it won't be possible to download the label in any other format later.

​
delivery_dates
Delivery Dates · object

Defined delivery dates. The handover_at date indicates when the item will be handed over to the carrier by the merchant in ISO 8601. If this date is not passed the carrier default will be used. For most carriers this is the following working day.

Response

Shipment response

Create a shipment

​
data
Sync shipment response Object · object

Sync shipment response object model