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",
          "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"
        ],
        "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",
            "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,
    "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
  }
}
​
from_address
Address Object · object
required

Sendcloud Address object

​
to_address
Address Object · object
required

Sendcloud Address object

​
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 panel and be retrieved (alongside their id) from the Retrieve a list of brands endpoint.

Example:

42

​
to_service_point
Service Point · object

Node for service point information. Use the Retrieve a list of service points endpoint to find service points.

​
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"

​
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" },
  "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"
      }
    ]
  }
}
​
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