7 Customs Declarations
7.1 Intro
The Customs Declaration endpoint has the possibilities to upload customs attachments, generate customs documents and send the commercial invoice of a customs declaration for Benelux customers to DHL without creating labels.
To auto-generate customs documents and send the commercial invoice as part of a shipment use create shipment.
Preconditions
An authorization token in the header of the HTTP request is mandatory. (see Authentication and Authorization).
7.2 Services
7.2.1 Upload attachment
This endpoint allows uploading customs attachments through Upload customs attachment.
Attachments can be included when creating shipment labels with customs or when sending a separate customs declaration.
A single attachment cannot be larger than 2.5 MB. Note that there are also limitations for the total size of all attachments in a customs declaration.
To upload an attachment, the attachment file contents need to be included as the raw request body. Unfortunately this is not supported by the Swagger version we currently use. To upload an attachment use the equivalent of
curl -i -X POST https://api-gw.dhlparcel.nl/customs/attachments/your_attachment_uuid \
-H "Authorization: Bearer your_api_token" \
-H "Content-Type: application/pdf" \
--data-binary "@path/to/file"
After a successful upload, attachments may be referenced using their UUID.
7.2.2 Get attachment by id
With the attachment id, a specific attachment can be retrieved through Get customs attachment by id.
The result depends on the content of the Accept header.
| Accept | Result |
|---|---|
| application/json | Detailed attachment information |
| application/pdf | PDF document with the attachment content |
7.2.3 Generate documents
This endpoint allows generating customs documents through Create customs document.
Depending on input details, a CN23 form or invoice is generated.
All generated customs documents are stored as attachments using the id field specified in the request body and can be retrieved later using Get attachment by id.
The following fields are unique to this endpoint
| Field | Type | Mandatory | Description |
|---|---|---|---|
| id | string | Y | Use a UUID Generator, attachmentId to store document |
In addition, the fields documented in Customs definitions must be provided.
The result depends on the content of the Accept header.
| Accept | Result |
|---|---|
| application/json | Detailed attachment information |
| application/pdf | PDF document with the attachment content |
7.2.4 Customs Declaration
This endpoint allows to send the commercial invoice of a customs declaration to DHL for Europlus (B2B) and Parcel Connect (B2C) shipments for Benelux customers with the option to generate customs documents as well through Create customs declaration.
All customs declarations are stored using the id field specified in the request body and can be retrieved later using Get declaration by id.
The following fields are unique to this endpoint
| Field | Type | Mandatory | Description |
|---|---|---|---|
| id | string | Y | Use a UUID Generator, declaration ID |
| attachmentIds | [string] | N | Specify custom attachments |
| createDocuments | boolean | N | Generate and include CN23 form or invoice |
In addition, the fields documented in Customs definitions must be provided.
Note: The combined size of all attachments is limited to 2.5 MB for Benelux.
7.2.5 Get Declaration by id
With the customs declaration id, a specific declaration can be retrieved through Get customs declaration by id.
7.3 Customs Definitions
| Field | Type | Mandatory | Description |
|---|---|---|---|
| accountId | string | Y | Account id as provided by DHL |
| product | string | Y | Product key as provided by the capabilities endpoint |
| pieceCount | integer | Y | Number of pieces in the shipment |
| orderReference | string | N | Reference for your own administration, should match REFERENCE shipment option when creating shipment labels |
| currency | string | N | Currency of the invoice, ISO (EUR, CHF, NOK, GBP, USD) |
| invoiceNumber | string | N | |
| remarks | string | N | Supplementary information, such as consignment remarks |
| invoiceType | string | N | Type of invoice, e.g. commercial |
| exportType | string | N | Permanent, Repair, Return, Temporary |
| exportReason | string | N | Other, SaleOfGoods, ReturnedGoods, Gift, CommercialSample, Documents |
| incoTerms | string | N | CFR, CIF, CIP, CPT, DAP, DAT, DDP, DDU, DDX, EXW, FCA, FOB; DDX means ‘DDP VAT Excl.’ EXW not applicable for UK exports. For Parcel Connect only DDU applicable to UK. |
| incoTermsCity | string | N | Named place of delivery/destination/port |
| defermentAccountDuties | string | N | Deferment Account for Duties (if a separate account exits for shipment to GB) |
| defermentAccountVat | string | N | Deferment Account for VAT (if a separate account exits for shipment to GB) |
| vatReverseCharge | boolean | N | |
| shipper | Y | Name and address | |
| string | N | ||
| phoneNumber | string | N | |
| vatNumber | string | N | |
| eoriNumber | string | N | |
| inboundVatNumber | string | N | Sender VAT number for inbound country. Only applicable for shipments to GB. Mandatory for Parcel Connect shipments to GB |
| name | Requires at least firstName, lastName or companyName | ||
| firstName | string | N | |
| lastName | string | N | |
| companyName | string | N | |
| additionalName | string | N | |
| address | Depending on country, use designated endpoint to check input address | ||
| countryCode | string | Y | |
| postalCode | string | Mandatory and format is checked based on country code | |
| city | string | Y | |
| street | string | Y | |
| number | string | N | |
| isBusiness | boolean | N | Defaults to true |
| addition | string | N | |
| receiver | Y | Name and address | |
| string | N | ||
| phoneNumber | string | N | |
| vatNumber | string | N | |
| eoriNumber | string | N | |
| name | Requires at least firstName, lastName or companyName | ||
| firstName | string | N | |
| lastName | string | N | |
| companyName | string | N | |
| additionalName | string | N | |
| address | Depending on country, use designated endpoint to check input address | ||
| countryCode | string | Y | |
| postalCode | string | Mandatory and format is checked based on country code | |
| city | string | Y | |
| street | string | Y | |
| number | string | N | |
| isBusiness | boolean | N | Defaults to true |
| addition | string | N | |
| importerOfRecord | N | Importer of the customs shipment | |
| string | N | ||
| phoneNumber | string | N | |
| vatNumber | string | N | |
| eoriNumber | string | N | |
| name | Requires at least firstName, lastName or companyName | ||
| firstName | string | N | |
| lastName | string | N | |
| companyName | string | N | |
| additionalName | string | N | |
| address | Depending on country, use designated endpoint to check input address | ||
| countryCode | string | Y | |
| postalCode | string | Mandatory and format is checked based on country code | |
| city | string | Y | |
| street | string | Y | |
| number | string | N | |
| isBusiness | boolean | N | Defaults to true |
| addition | string | N | |
| shippingFee | Additional shipping fee | ||
| currency | string | Y | |
| value | string | Y | |
| customsGoods | Y | Customs goods in this declaration, at least one is required | |
| code | string | Y | HS-code of the goods, see Harmonized commodity description and coding System, to classify globally traded products. Always 8 or 10 positions. |
| description | string | Y | Description of the goods |
| origin | string | Y | Country of origin, ISO 3166-1 alpha-2 country code |
| quantity | string | Y | Number of the products of this line |
| value | string | Y | Total value of the goods of this line |
| weight | string | Y | Net weight of the products of this line |
7.4 Testing
The test system of the DHL-customer should be connected to the test system of DHL.
Please create test cases which are suitable for your line of business or wishes.
7.5 Customs Declarations V1 (deprecated)
*Deprecated, please use Customs Declarations V2 to create a shipment with customs information. While this endpoint will be supported, new features will be added only to Customs Declarations V2
7.5.1 Intro
The Customs Declaration endpoint has the possibility to send the commercial invoice of a customs declaration to DHL for Europlus (B2B) and Parcel Connect (B2C) shipments. This is only applicable for customs destinations. It is also possible to send the customs documents T1, T2, EU-A, EU-Z using this endpoint.
Preconditions
An authorization token in the header of the HTTP request is mandatory. (see Authentication and Authorization).
7.5.2 Services
7.5.2.1 Customs Declaration
*Deprecated, use Customs Declaration to create a customs declaration for Europlus or Parcel Connect shipments to customs destinations.
This endpoint creates a customs declaration for Europlus or Parcel Connect shipments to customs destinations.
In order to create a customs declaration, a unique identifier is needed as input for the request. The format for this identifier is the Universally Unique Identifier (UUID). The use of UUIDs keeps our API idempotent. It ensures in this case that a declaration is created uniquely and just once, without needing to do any expensive and complicated synchronized bookkeeping.
Most programming languages and platforms have a built-in UUID generator that you can use for this purpose. A brief explanation on the other input data is given in the table below.
| Field | Type | Mandatory | Description |
|---|---|---|---|
| orderNumber | string | Y | OrderReference of the shipment. Together with your customernumber this is a reference number to the shipment |
| uuid | String | Y | Use a UUID Generator |
| customerNumber | string | Y | AccountID, accountnumber (received from DHL) you are using for the shipment. |
| numUnitsDocumented | Integer | Y | Number of packages of the shipment (normally equal to number of labels created for DHL). |
| createdBy | Do not use | ||
| commercialInvoice | Y | Commercial Invoice | |
| incoterm | String | Y | Supported incoterms: CFR, CIF, CIP, CPT, DAP, DAT, DDP, DDU, DDX, EXW, FCA, FOB. DDX means “DDP VAT Excl.” EXW is not supported for GB exports. For Parcel Connect shipments to GB only DDU is supported. |
| incotermCity | String | Y | Named place of delivery/destination/port |
| invoiceNumber | String | Y | The invoice number |
| invoiceDate | YYYY-MM-DD | Y | The date of the invoice |
| reasonForExportCode | String | N | Supported Codes: 9 – Others 11 – Sale of goods 21 – Returned goods 31 – Gift 32 – Commercial sample 91 – Documents In case no code provided, default value will be 11. |
| currency | String | Y | Currency of the invoice, ISO (EUR, CHF, NOK, GBP, USD) |
| amount | Number (19,2) | Y | Total value of the shipment. |
| freightCosts | Number (19,2) | N | In case freight costs are separate on the invoice |
| insuranceCosts | Number (19,2) | N | In case insurance costs are separate on the invoice |
| otherCosts | Number (19,2) | N | In case other costs are separate in the invoice. Can be negative (for discounts) |
| totalWeightKg | Number | Total weight in kg | |
| defermentAccountVat | String | N | Deferment Account VAT |
| defermentAccountDuties | String | N | Deferment Account for Duties (if a separate account exits) |
| Receiver | Y | Receiver of the goods (conform the invoice) | |
| name | String | Y | |
| addressLine1 | String | Y | |
| addressLine2 | String | N | |
| addressLine3 | String | N | |
| postalCode | String | Y | |
| city | String | Y | |
| countryCode | String (2) | Y | ISO-3166 alpha-2 |
| phone | String | N | Mandatory for shipments to GB |
| String | N | Mandatory for shipments to GB | |
| eoriCountryCode | String (2) | N | First characters of the EORI number, indicating the country-code. |
| eoriNumber | String | N | Remaining characters of the EORI number. |
| vatCountryCode | String (2) | N | First characters of the VAT number, indicating the country-code. Mandatory for Europlus shipments to GB. |
| vatNumber | String | N | Remaining characters of the VAT number. Mandatory for Europlus shipments to GB. |
| Shipper | Y | Exporter of the goods (conform the invoice) | |
| name | String | Y | |
| addressLine1 | String | Y | |
| addressLine2 | String | N | |
| addressLine3 | String | N | |
| postalcode | String | Y | |
| city | String | Y | |
| countryCode | String (2) | Y | ISO-3166 alpha-2 |
| eoriCountryCode | String (2) | Y | First characters of the eori-number, indication the country-code. |
| eoriNumber | String | Y | Remaining characters of the eori-number. |
| vatCountryCode | String (2) | Y | First characters of the VAT-number, indication the country-code |
| vatNumber | String | Y | Remaining characters of the VAT-number |
| phone | String | N | |
| String | N | Mandatory for shipments to GB | |
| inboundVatCountryCode | String (2) | N | First characters of the inbound country VAT number, indicating the country-code. Mandatory for Europlus shipments to GB. Currently only applicable to shipments to GB. Mandatory for Parcel Connect shipments. |
| inboundVatNumber | String | N | Remaining characters of the inbound country VAT number. Mandatory for Parcel Connect shipments. |
| InvoiceLines | Y | At least one invoice line is mandatory | |
| description | String | Y | Description of the goods |
| hsCode | Number-10 | Y | HS-code of the goods, see Harmonized commodity description and coding System, to classify globally traded products. Always 8 or 10 positions. |
| netWeightKg | Number | Y | Total netto weight of the products of this line |
| numParts | Number | Y | The number of the products of this line |
| countryOfOrigin | String (2) | Y | ISO-3166 alpha-2 |
| value | Number | Y | The total value of the goods of this line. Should be higher than “0” |
| predeclaredDocuments | N | Optional, only used in case a T1, T2 or EU-document is already created for the shipment. | |
| documentType | String (4) | Y | T1, T2, EU-A, EU-Z |
| documentNumber | String | Y | The number of the document |
| Attachments | N | The invoice (in PDF). Preferred the invoice is given in the API. The invoice must also be attached to the goods. The invoice is mandatory for shipments with destination GB. | |
| name | String | Y | |
| mimeType | String | Y | Always "application/pdf" |
| Content | String | Y | The invoice in pdf-format (base-64). |
7.5.3 API Usage
| Description | URL |
| Create customs declaration (prod) | https://api-gw.dhlparcel.nl/customs/declarations |
Note: For testing, collect your **Sandbox** API key in My DHL eCommerce
Responses
Success
Code 200
Failure:
Code 400 Bad request
Code 401 Unauthorized, invalid header Authorization: Bearer
Code 500 Internal server error
Code 503 Service unavailable, likely a database error
| Code | Integer | Y | |
|---|---|---|---|
| Message | String | Y |