Customs

When shipping between countries, it is often required to declare customs. This guide will go through how to add customs to your shipment request, so that these documents can be generated.

Customs implementation

Whether or not a product requires customs it can be found from the /products endpoint. If the field customs_declaration_required is true, a customs object should always be there.

warning

The customs_declaration_required field under destination_country is deprecated, use the one under the product itself.

The customs part of a shipment request is an object that contains overall data for customs, as well as an array of goods associated with it. In the object itself, only the currency code is required. If you need to specify terms of trade, and duty payment type, you can also do that here.

Declaring the goods is done through the goods array. Here you define quantity, country_code (ISO 3166-1 alpha-2), content, commodity_code (tariff code), unit_value of the items, and unit_weight of the items. If there are more than one type of item, a separate goods object is added to the goods array. Following example is a simple version of customs declaration:

"customs": {
  "currency_code": "DKK",
  "goods": [
    {
      "quantity": 2,
      "country_code": "NO",
      "content": "T-shirt",
      "commodity_code": "61091000",
      "unit_value": 30.10,
      "unit_weight": 1000
    }
  ] 
}

The customs object is then added to the shipment request.

{
  "test_mode": false,
  "own_agreement": true,
  "product_code": "DHLE_EW",
  "service_codes": "",
  "sender": {
    "name": "Pakkelabels.dk ApS",
    "address1": "Strandvejen 6",
    "zipcode": "5240",
    "city": "Odense NØ",
    "country_code": "DK",
    "email": "firma@email.dk",
    "mobile": "70400407"
  },
  "receiver": {
    "name": "University of Oslo",
    "address1": "Problemveien 7",
    "zipcode": "0315",
    "city": "Oslo",
    "country_code": "NO",
    "email": "lene@email.dk",
    "mobile": "50607080"
  },
  "parcels": [
    {
      "weight": 2000,
      "length": 10,
      "width": 10,
      "height": 10
    }
  ],
  "print": true,
  "print_at": {
    "host_name": "LAPTOP-PKL",
    "printer_name": "GK420D",
    "label_format": "zpl"
  },
  "customs": {
    "currency_code": "DKK",
    "goods": [
      {
        "quantity": 2,
        "country_code": "NO",
        "content": "T-shirt",
        "commodity_code": "61091000",
        "unit_value": 30.10,
        "unit_weight": 1000
      }
    ] 
  },
  "reference": "Order 44"
}

It is possible to declare other properties for customs. Use only the ones agreed with the carrier.

"customs": {
  "export_reason": "other",
  "term_of_trade": "DAP",
  "duty_payment_type": "S",
  "duty_account_number": "AB123456",
  "billed_to_name": "Virksomhed AS",
  "billed_to_attention": "Erik Olsen",
  "billed_to_address1": "Strandvejen 68",
  "billed_to_address2": "",
  "billed_to_zipcode": "0400",
  "billed_to_city": "Oslo",
  "billed_to_country": "NO",
  "billed_to_telephone": "004767896789",
  "billed_to_mobile": "004767896789",
  "billed_to_email": "erik@virksomhed.no",
  "billed_to_vat_id": "976 390 512",
  "contents": "Textile clothes",
  "currency_code": "DKK",
  "goods": [
    {
      "quantity": 2,
      "country_code": "NO",
      "content": "T-shirt",
      "commodity_code": "61091000",
      "unit_value": 30.10,
      "unit_weight": 1000
    }
  ]
}

One these are export_reason where you are able to define the category of the export.

The valid values are:

• gift
• documents
• commercial_samples
• returned_goods
• other
• sale_of_goods

info

sale_of_goods is only available for some specific carriers. If you use it for any other carrier it will be set as other

Goods validation

The objects in the goods array gets validated on a set of rules.

A general rule is that all fields should be present and they should have a value.

Field specific rules are as follows

• quantity must be greater than 0
• country_code must be a valid ISO 3166-1 alpha-2 country code
• content must have a length greater than 0
• commodity_code must be a string that only include digits and have a length of either 6, 8, 10 or 12 digits
• unit_value must be greater than 0
• unit_weight must be greater than 0

If one or more objects fails to validate these rules, an error is returned with the fields affected.

An example of this could be:

"customs": {
  "currency_code": "DKK",
  "goods": [
    {
      "quantity": 2,
      "country_code": "NO",
      "content": "T-shirt",
      "commodity_code": "61091000",
      "unit_value": 30.10,
      "unit_weight": 0
    }
  ] 
}

unit_weight fails to validate since it does not have a value greater than 0.

So the API would return the error One or more customs goods are missing or have invalid values in unit weight.