Skip to main content
POST
/
shipments
/
announce-with-shipping-rules
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/shipments/announce-with-shipping-rules \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apply_shipping_defaults": true,
  "apply_shipping_rules": true,
  "delivery_indicator": "DHL home delivery",
  "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"
      },
      "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"
          }
        }
      ]
    }
  ]
}
'
{
  "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": []
  }
}
The main advantage of this endpoint over the Create and announce a shipment synchronously endpoint (and also the difference between them) is the ability to apply shipping rules and shipping defaults to a shipment. Because of this, more fields in this endpoint are optional. Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (Basic ...).

​
Development status

This endpoint is currently in beta, meaning that it is still under development. During this phase, we continually monitor and test the API to improve its performance, review the requested and the returned data, and uncover any potential bugs that could have a future impact on our users.
Please note that there is a possibility you may experience breaking changes while the endpoint is still in beta.

​
Shipping rules

  • Due to the data (shipments) that we receive in this API, NOT all of the shipping rules (actions or conditions) can (and will) be applied.
  • Shipping rules do not fully apply to multicollo shipments. In such cases, the rule conditions for weight, parcel dimensions (height, length, width), total order value, item name, item quantity, item SKU and total parcel item value will not be matched. Additionally, the following actions will not be triggered:
    • Using a box (Use box)
    • Setting the weight (Set weight)
    • Setting the number of parcels (Set number of parcels)
    • Insuring the shipment value (Insure shipment value by)
    • Insuring it by percentage (Insure shipment value by %)
    • Increasing item value by percentage (Decrease item value by %)
    • Setting item HS code (Set Item HS Code)
    • Setting item name (Set item name)
    • Setting item origin country (Set Item Origin Country)
    • Setting item value (Set item value)
    • Setting item weight (Set item weight)
Please consider these limitations when defining rules.

​
Shipping rules conditions (IF) that can be applied

  • Carrier
  • Checkout delivery method
  • Company name
  • Customer email
  • Integration
  • Item SKU
  • Item name
  • Item quantity
  • Parcel height (cm)
  • Parcel length (cm)
  • Parcel width (cm)
  • Phone number
  • Postal code
  • To country
  • Total order value
  • Total parcel item value
  • Weight (kg)

​
Shipping rules actions (THEN) that can be applied

  • Add customs declaration statement
  • Use box
  • Decrease item value by %
  • Insure shipment value by
  • Insure shipment value by %
  • Set customs general notes
  • Set customer email
  • Set Item HS Code
  • Set item name
  • Set Item Origin Country
  • Set item value
  • Set item weight
  • Set number of parcels
  • Phone number
  • Ship with address
  • Ship with
  • Set weight
  • Use shipping contract

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

Asynchronous Shipment with Rules request object model

​
to_address
Address Object · object
required

Sendcloud Address object

​
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

​
ship_with
Ship with object · object

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

Sendcloud Address object

​
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 with optional fields · 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.

​
parcels
Parcel common with optional fields Object · object[]

Represents each package of the shipment. Each carrier can have its own number of parcels limit per shipment, otherwise there is a restriction to a maximum of 50 parcels (default).

Required array length: 1 - 50 elements
​
apply_shipping_defaults
boolean
default:true

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.

Example:

true

​
apply_shipping_rules
boolean
default:true

When set to true, shipping rules will be applied.

**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 panel's Incoming Orders overview, not all shipping rules can be applied.

Example:

true

​
delivery_indicator
string

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

Learn more about Shipping rules.

Example:

"DHL home delivery"

Response

Shipment response

Create a shipment

​
data
Sync shipment response Object · object

Sync shipment response object model