Shipments

Create a shipment with rules and/or defaults and announce it synchronously

Create and announce a shipment applying shipping rules and/or defaults

post/shipments/announce-with-shipping-rules

Headers

Sendcloud-Partner-Idstring

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

brand_idinteger

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.

order_numberstring

Order number generated manually or by shop system

referencestring nullable

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

external_reference_idstring nullable

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.

validation_methodsAddressValidationMethodEnum[]

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.

When using this field you authorize Sendcloud to automatically correct shipping addresses using third-party address validation services. You understand that these corrections are not guaranteed to be accurate and that you remain responsible for the shipping information used for your shipments.

apply_shipping_defaultsboolean

When set to true, the "Default weight", "Preferred shipping method" and "Default export reason" shipping defaults will be applied, if they were not provided by the request payload.

Note that the request payload values and shipping rules take precedence over these defaults.

apply_shipping_rulesboolean

When set to true, shipping rules will be applied.

<Info> **Note that rules take precedence over the values provided in the request payload and over the [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults).**

For instance, if a contract is specified in one of the applicable rules for the shipment that is being requested, the contract value provided in the request payload will be ignored.

Also keep in mind that since orders created by the API do not appear in the Sendcloud platform's Incoming Orders overview, not all shipping rules can be applied. </Info>

delivery_indicatorstring

Free text that is intended for applying the Checkout Delivery Method condition in shipping rules.

Learn more about Shipping rules.

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

dataSyncShipmentWithRulesResponse — unresolved $ref

Changes

Changed in 3 of the 5 revisions of this API.29

  • 4dbce94b69be21See the full diff
    • added dhl-freight-shipment-extras to the allOf[subschema #1: Base shipment response Object]/allOf[subschema #1: Shipment common Object]/allOf[subschema #1: Shipment common with optional fields Object]/carrier_fields response property oneOf list for the response status 409

      response-property-one-of-added

    • added dhl-freight-shipment-extras to the data/allOf[subschema #1: Base shipment response Object]/allOf[subschema #1: Shipment common Object]/allOf[subschema #1: Shipment common with optional fields Object]/carrier_fields response property oneOf list for the response status 201

      response-property-one-of-added

    • added dhl-freight-shipment-extras to the allOf[subschema #1: Shipment request with optional fields Object]/allOf[subschema #1: Shipment common with optional fields Object]/carrier_fields request property oneOf list

      request-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_time

      new-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_time

      new-optional-request-property

    • added the optional property allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/earliest_delivery_time to the response with the 409 status

      response-optional-property-added

    • added the optional property allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/latest_delivery_time to the response with the 409 status

      response-optional-property-added

    • added the optional property data/allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/earliest_delivery_time to the response with the 201 status

      response-optional-property-added

    • added the optional property data/allOf[subschema #1: Base shipment response Object]/allOf[subschema #2]/delivery_dates/latest_delivery_time to the response with the 201 status

      response-optional-property-added

    • added the optional property allOf[subschema #2]/parcels/items/allOf[subschema #1: Parcels Array Response Object]/allOf[subschema #2]/tracking_numbers to the response with the 409 status

      response-optional-property-added

    • added the optional property data/allOf[subschema #2]/parcels/items/allOf[subschema #1: Parcels Array Response Object]/allOf[subschema #2]/tracking_numbers to the response with the 201 status

      response-optional-property-added