Customs documents
Customs documents are always required for parcels shipping to destinations outside the EU. In most cases a commercial invoice is required by commercial carriers (e.g. UPS and DHL), however postal carriers (e.g. PostNL and Royal Mail) require a CN22 or CN23 form. Sendcloud automatically generates the correct type of documentation when you create an international shipment through the Shipments API. You just need to include some additional properties in your request, as listed below.Required fields for international shipments
When you create a shipment for an international destination, you need to include the properties below in your request. This ensures that customs documentation can be rendered correctly, and that the items in your shipment are listed alongside their value and description.Parcel item object
Include the following properties in each object in a parcel’sparcel_items array:
Some destinations and carriers need extra item details, such as
mid_code for U.S. formal customs entries. See the parcel_items schema in Create and announce a shipment synchronously for all available fields.
Example international shipment (excerpt)
Tip: Adding items to commercial invoices & CN22/23 customs formsThe amount of items you can include on a single commercial invoice differs depending on the type of shipping carrier you have selected. For a full overview, refer to our help center
Migrating from the v2 Parcels API
If you’re moving an integration from the v2 Create a parcel endpoint, the v2 fields map to v3 as follows:description, quantity, hs_code, origin_country, sku, product_id and properties keep the same names.
Providing additional customs information with the customs_information object
The customs_information object contains customs information that should be provided for international shipments, such as the invoice number, export reason, additional costs, importer of record and tax numbers. invoice_number (up to 40 characters) and export_reason are required. See the customs_information schema in Create and announce a shipment synchronously for all fields.
Tax numbers go in the tax_numbers object, split into sender, receiver and importer_of_record lists. They are validated as follows:
- VAT and EORI numbers must have a valid format for their
country_code. sender: for commercial exports (export_typeiscommercial_b2corcommercial_b2b), you must provide a VAT number for the sender country or the invoice address country.export_typedefaults tocommercial_b2c, so set it toprivatefor private shipments. This check is skipped when you ship with your own carrier contract.importer_of_record: the country code must match the destination country code.receiver: whenexport_typeiscommercial_b2b, the country code must match the destination country code.- IOSS and EORI numbers are exempt from these country code checks.
Downloading customs documents
Once you have created an international shipment, each parcel in the response contains its documents in thedocuments array.
Example response body (excerpt)
link provided in the response, or via the Retrieve a parcel document endpoint by providing the parcel id and customs-declaration as the document type.
Tip: Paperless tradeSendcloud supports digital sending of customs documents for carriers who support Paperless trade. You can find a list of supporting carriers in our help center.