SEsendcloud
Shipments

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

Changed on

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

post/shipments/announce-with-shipping-rules

Request

  • Base URL
    https://panel.sendcloud.sc/api/v3
  • URL
    https://panel.sendcloud.sc/api/v3/shipments/announce-with-shipping-rules
  • Auth
    • HTTP basic
    • or OAuth 2
      Client credentials
      Token URL: https://account.sendcloud.com/oauth2/token/ scopes: write:parcel, read:shipping-rule

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.

When a shipment is created without a brand_id, the brand of the sender address in from_address.sender_address_id is used. If the full from_address is provided instead, no brand is applied and brand_id is null. See Brands for details.

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 recognized 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"
        }
      ]
    },
    "mrn": "25NLQ8PF0V3DJ1MKX7"
  },
  "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": 0.5,
            "unit": "kg"
          },
          "price": {
            "value": "10.00",
            "currency": "EUR"
          },
          "hs_code": "620520",
          "origin_country": "NL",
          "sku": "TS1234",
          "cpsc": {
            "product_id": "12345",
            "certifier_id": "67890",
            "version_id": "1"
          }
        }
      ]
    }
  ],
  "apply_shipping_defaults": true,
  "apply_shipping_rules": true,
  "delivery_indicator": "DHL home delivery"
}

Response

Shipment response

Example response

{
  "data": {
    "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
    },
    "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"
          }
        ]
      },
      "mrn": "25NLQ8PF0V3DJ1MKX7"
    },
    "from_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"
    },
    "to_service_point": {
      "id": "123",
      "carrier_service_point_id": "91233"
    },
    "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"
    },
    "carrier": {
      "code": "postnl",
      "name": "PostNL"
    },
    "announced_by": {
      "id": 12345,
      "name": "Marie Doe",
      "email": "marie.doe@example.com"
    },
    "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": 0.5,
              "unit": "kg"
            },
            "price": {
              "value": "10.00",
              "currency": "EUR"
            },
            "hs_code": "620520",
            "origin_country": "NL",
            "sku": "TS1234",
            "cpsc": {
              "product_id": "12345",
              "certifier_id": "67890",
              "version_id": "1"
            }
          }
        ],
        "created_at": "2024-09-04T12:14:36.506925Z",
        "updated_at": "2024-09-04T12:14:47.203107Z",
        "announced_at": "2024-09-04T12:14:47.153985Z",
        "status": {
          "code": "ANNOUNCING",
          "message": "Being announced"
        },
        "tracking_number": "3SYZXG8498635",
        "tracking_numbers": [
          {
            "tracking_number": "3SYZXG8498635"
          }
        ]
      }
    ],
    "label_details": {
      "mime_type": "application/zpl",
      "dpi": 300
    },
    "applied_shipping_rules": [
      {
        "rule": {
          "id": 315157,
          "name": "Ship with PostNL for NL"
        },
        "result": {
          "shipping_option_code": "postnl:standard"
        }
      }
    ]
  }
}

Changes

  • bd2563dc7241Revision changes
    • breaking

      added subschema #2 subschema #3 to the / request property allOf list

    • warning

      removed subschema #2 subschema #3 from the / request property allOf list

    • warning

      added the new VOEC enum value to the //////// response property for the response status

    • warning

      added the new VOEC enum value to the //////// response property for the response status

    • warning

      added the new VOEC enum value to the //////// response property for the response status

    • warning

      added the new VOEC enum value to the ///////// response property for the response status

    • warning

      added the new VOEC enum value to the ///////// response property for the response status

    • warning

      added the new VOEC enum value to the ///////// response property for the response status

  • fad3b495f9c1Revision changes
    • info

      added the required property /// to the response with the status

    • info

      added the required property //// to the response with the status