SEsendcloud
Shipments

Create and announce a shipment synchronously

Changed on

This endpoint announces a shipment synchronously under your API credentials.

post/shipments/announce

Request

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

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.

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
  },
  "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": {
    "sender_address_id": 192
  },
  "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"
          }
        }
      ]
    }
  ]
}

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
    }
  }
}

Changes

  • bd2563dc7241Revision changes
    • 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

    • info

      added the new VOEC enum value to the request property ////////

    • info

      added the new VOEC enum value to the request property ////////

    • info

      added the new VOEC enum value to the request property ////////

  • fad3b495f9c1Revision changes
    • info

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

    • info

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