API documentation Declarations

Contents

Get declaration information

Provides all available information about a parcel's most recent declaration, such as the VAT and duty estimates, timestamps of major events such as customs controls and clearing.

Endpoint

[GET] /v4/parcels/{client_ref}/declaration

Attributes

Key Description Datatype Constraints
act_payable_duties Duties, officially determined by Customs Integer In cents, e.g. 250 stands for 2.50€. Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all duties on this declaration is displayed. On the product level, only individual duties for one product are displayed.
act_payable_vat VAT, officially determined by Customs Integer In cents, e.g. 10 stands for 0.10€ Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all duties on this declaration is displayed. On the product level, only individual duties for one product are displayed.
customs_value Customs value, determined by ViaEurope Integer In cents, e.g. 10 stands for 0.10€ Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all customs values on this declaration is displayed. On the product level, only the individual customs value for one product are displayed.
intrinsic_value Intrinsic value, calculated by ViaEurope Integer In cents, e.g. 250 stands for 2.50€. Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all intrinsic values on this declaration is displayed. On the product level, only individual intrinsic values for one product are displayed.
est_payable_duties Duties, estimated by ViaEurope Integer In cents, e.g. 250 stands for 2.50€ Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all duties on this declaration is displayed. On the product level, only individual duties for one product are displayed.
est_payable_vat VAT, estimated by ViaEurope Integer In cents, e.g. 10 stands for 0.10€ Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all duties on this declaration is displayed. On the product level, only individual duties for one product are displayed.
est_sales_vat Sales VAT, estimated by ViaEurope Integer In cents, e.g. 10 stands for 0.10€ Note this key appears under the top level, as well as under the product keys. On the top level, the sum of all duties on this declaration is displayed. On the product level, only individual duties for one product are displayed.
sales_vat_percentage Sales VAT percentage in the country of declaration Float 0.19 stands for 19% Note this key appears under the top level, as well as under the product keys.
cleared_at Timestamp when customs "cleared" response was received Timestamp
put_in_control_at Timestamp when customs "control" response was received Timestamp
state State of declaration String Can be
  • pending
    declaration has not been sent to Customs yet
  • canceled
    declaration was canceled by the client
  • screening
    declaration was marked for screening by ViaEurope
  • spotcheck
    declaration was marked for spot check by ViaEurope
  • rejected
    declaration has been rejected by ViaEurope due to the presence of incorrect, insufficient or now outdated information during
    • Spot check
    • Screening
    • VAT check
    • Representative check
  • control
    declaration is under control by Customs
  • exception
    declaration is not following normal workflow. Currently, this can only happen if Customs seized a parcel (e.g. because of counterfeit goods)
  • cleared
    declaration was cleared by Customs
long_haul_type Parcel's mode of transport String When present, can be
  • air
  • rail
  • road
  • sea
base_value Product's base value, for all pieces, as entered by the client String
declarable_long_haul_cost Exact IOSS declarable long haul cost (i.e. mainly outside EU share) for all pieces of this product. Contact support to confirm eligibility to provide this value. String Must be absent unless eligibility confirmed by support.
force_general_clearance Submit customs declaration using general clearance method independent from goods value. Boolean
description Product's description, as entered by the client String
quantity Product's quantity, for all pieces, as entered by the client String
weight Product's weight, for all pieces, as entered by the client String

Example

Response

{
  "act_payable_duties": 1330,
  "act_payable_vat": 0,
  "customs_value": 12345,
  "cleared_at": "2018-09-26T11:33:28.300+02:00",
  "est_payable_duties": 1330,
  "intrinsic_value": 109000,
  "force_general_clearance": false,
  "long_haul_type": null,
  "est_payable_vat": 0,
  "est_sales_vat": 0,
  "sales_vat_percentage": 0,
  "put_in_control_at": null,
  "state": "cleared",
  "products": [
    {
      "act_payable_duties": 958,
      "act_payable_vat": 0,
      "base_value": 88726,
      "client_ref": "abc-789",
      "customs_value": 66341,
      "intrinsic_value": 77000,
      "description": "KETTLE BAG",
      "est_payable_duties": 958,
      "est_sales_vat": 0,
      "sales_vat_percentage": 0,
      "est_payable_vat": 0,
      "marketplace_url": "http://www.amazon.de/123",
      "original_taric": "1234567890",
      "quantity": 74,
      "taric": "1234567890",
      "weight": 11100
    },
    {
      "act_payable_duties": 372,
      "act_payable_vat": 0,
      "base_value": 34450,
      "intrinsic_value": 32000,
      "client_ref": "abc-789",
      "customs_value": 20334,
      "description": "BACKPACK",
      "est_payable_duties": 372,
      "est_payable_vat": 0,
      "est_sales_vat": 0,
      "sales_vat_percentage": 0,
      "marketplace_url": "http://www.amazon.de/123",
      "original_taric": "1234567890",
      "quantity": 5,
      "taric": "1234567890",
      "weight": 3000
    }
  ],
  "released_at": null
}

Create new declaration

Creates a new declaration in the ViaEurope system. This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors. Note that any previous, pending declarations must be canceled prior to assigning a new declaration to a parcel

Endpoint

[POST] /v4/parcels/{client-ref}/declaration

Attributes

Key Description Datatype Constraints Errors
type Type of declaration String The following types are available, dependent on declaration_country value:
  • sale_b2c_x Sale B2C, version x, NL and BE
  • sale_b2b_x Sale B2B, version x, NL only
  • sale_c2c_x Sale C2C, version x, NL only
  • marketplace_x Marketplace, version x, NL and BE
It is very important that you choose the correct type.
  • Type is invalid
declaration_country Country in which products will be declared to Customs String Must be a 2-letter ISO 3166-2 code. Currently available: NL (Netherlands), BE (Belgium, regular parcels only) and HU (Hungary). See type for more information.
country_of_export Country from which the products were exported String Must be a 2-letter ISO 3166-2 code, e.g. CN
  • Country of export can't be blank
  • Country of export must be an ISO 3166-2 code, one of AU, GB, CN, HK, IN, LK, TR or US
origin_client_ref Internal reference for original client String Optional. 5-30 characters, must only contain characters A-Z, 0-9, minus and underscore
  • Origin client ref must only contain characters A-Z, 0-9, minus and underscore
  • Origin client ref is too short (minimum is 5 characters)
  • Origin client ref is too long (maximum is 30 characters)
ioss_number Registered VIAIOSS reference (see here or I-OSS number of shipper String Optional. Mandatory for B2C declarations in DE, BE, HU. Mandatory if import VAT exemption must be claimed at import. The I-OSS number can only be from the Seller or if sold through a platform the I-OSS number of the platform. Must be either:
  • format "IM" followed by 10 digits in range 0-9, example:
    IM1234567890
  • a reference of a IOSS number previously registered in the portal, example:
    VIAIOSS-9999999999
  • a Base64-encoded RSA-1024 encrypted I-OSS number using the public key provided by ViaEurope
  • IOSS number is unknown or not yet fully registered
  • IOSS number is invalid
  • IOSS number not allowed for this type of declaration
  • IOSS number encrypted number not allowed
vat_number VAT number of shipper/consignee String Optional. Mandatory when the VAT is deferred at import. The VAT number of the shipper (in case type is Marketplace), the seller (in case of Sale B2C) or of the consignee (in case type is Sale B2B).
  • VAT number needs to be permitted before it can be used
  • VAT number and POA number must be used together
  • VAT number is mandatory for Marketplace BE declarations (because they can only be used when VAT is deferred)
  • VAT number must be in the same country/
poa_number POA number String Optional. Mandatory when the VAT is deferred at import. You receive a POA number from ViaEurope if you use our VAT deferment service.
  • Poa number is unknown
representative_eori_number Representative EORI number String Optional. Mandatory for B2B and B2B2C. Indicates demand for direct Customs representation. Only for registered clients. Contact support to register.
  • Representative EORI number and Representative POA number must be used together
  • Client is not entitled to use direct representation
  • Representation registration has not been approved
representative_poa_number Representative POA number String Optional. Mandatory for B2B and B2B2C. Indicates demand for direct Customs representation. Only for registered clients. Contact support to register.
  • Representative EORI number and Representative POA number must be used together
consignee Consignee of parcel JSON Optional. Mandatory if no delivery was booked for the parcel, or when doing a dry run
  • Consignee address is outside EU VAT area
  • Consignee address must exist
consignee > shortcode Name String Optional. An alternative to passing full address parameters. When submitting address data, it's possible to send only shortcode and name1, and the rest of the attributes (name2, street, city, zip, country) will be selected and assigned by matching the shortcode.
  • Shortcode and address data do not match. You can leave out name2, street, city, zip, country when using a shortcode
  • Shortcode is not included in the list
consignee > name1 Name String Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name1 can't be blank
  • Name1 is too long (maximum is 35 characters)
  • Name1 must only contain latin or printable ASCII characters
  • Name1 must not contain multiple lines
consignee > name2 Name (continued) String Optional. Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name2 must only contain latin or printable ASCII characters
  • Name2 is too long (maximum is 35 characters)
  • Name2 must not contain multiple lines
consignee > street Street String Maximum 70 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks. Must not contain zip code. Must not contain city.
  • Street can't be blank
  • Street is too long (maximum is 70 characters)
  • Street must not contain city, building, or company name
  • Street must only contain latin or printable ASCII characters
  • Street must not contain multiple lines
consignee > city City String 2-35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • City can't be blank
  • City is too short (minimum is 2 characters)
  • City is too long (maximum is 35 characters)
  • City must only contain latin or printable ASCII characters
  • City must not contain multiple lines
consignee > country Country String 2 character ISO 3166-Alpha 2 country code. See Countries list for more information.
  • Country can't be blank
  • Country is unknown or not supported
  • Country is invalid
consignee > zip Zip String Zipcode associated with the address
  • ZIP can't be blank
  • ZIP has invalid format (country-specific)
consignee > email Email of recipient String Optional. Maximum 50 characters
  • Email can't be blank
  • Email is not a valid email address
  • Email is too long (maximum is 50 characters)
consignee > phone Phone number String Optional. Maximum 15 characters. Must only contain characters 0-9, plus and minus.
  • Phone can't be blank
  • Phone must only contain characters 0-9, plus and minus
  • Phone is too long (maximum is 25 characters)
exporter Exporter of parcel JSON Optional.
exporter > name1 Name String Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name1 can't be blank
  • Name1 is too long (maximum is 35 characters)
  • Name1 must only contain latin or printable ASCII characters
  • Name1 must not contain multiple lines
exporter > name2 Name (continued) String Optional. Maximum 35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • Name2 must only contain latin or printable ASCII characters
  • Name2 is too long (maximum is 35 characters)
  • Name2 must not contain multiple lines
exporter > street Street String Maximum 70 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks. Must not contain zip code. Must not contain city.
  • Street can't be blank
  • Street is too long (maximum is 70 characters)
  • Street must not contain city, building, or company name
  • Street must only contain latin or printable ASCII characters
  • Street must not contain multiple lines
exporter > city City String 2-35 characters. Must only contain latin or printable ASCII characters. Must not contain line breaks.
  • City can't be blank
  • City is too short (minimum is 2 characters)
  • City is too long (maximum is 35 characters)
  • City must only contain latin or printable ASCII characters
  • City must not contain multiple lines
exporter > country Country String 2 character ISO 3166-Alpha 2 country code.
  • Country can't be blank
  • Country is unknown or not supported
  • Country is invalid
exporter > zip Zip String Zipcode associated with the address
  • ZIP can't be blank
  • ZIP has invalid format (country-specific)
exporter > email Email of recipient String Optional. Maximum 50 characters
  • Email can't be blank
  • Email is not a valid email address
  • Email is too long (maximum is 50 characters)
exporter > phone Phone number String Optional. Maximum 15 characters. Must only contain characters 0-9, plus and minus.
  • Phone can't be blank
  • Phone must only contain characters 0-9, plus and minus
  • Phone is too long (maximum is 25 characters)
force_general_clearance Submit customs declaration using general clearance method independent from goods value. Boolean Optional
  • Force general clearance is invalid
products Goods contained in parcel Array of JSON Please use one entry per kind of goods (same description and taric code).
  • Products can't be blank
description Description of product Array of JSON 3-70 characters, must only contain characters A-Z, 0-9, minus and underscore
  • Description can't be blank
  • Description is too short (minimum is 3 characters)
  • Description is too long (maximum is 70 characters)
  • Description must not contain multiple lines
  • Description must only contain latin or printable ASCII characters
  • Description must not contain the word "gift"
  • Description must not contain the word "gadget"
taric European HS code String Taric code (10 digits) or HS-code (6 digits, allowed for Sale B2C 4 only). Invalid HS Codes are not accepted. You can use the ViaEurope taric lookup to find the right Taric Code.
  • Taric is invalid
base_value Declared value for total quantity of this product Integer Must be in cents. Value depends on used declaration type.
Example: 15 pieces in the parcel, each piece costs 2.30€.
base_value should be 15 pieces * 2.30€ per piece * 100 cents per € = 3450 cents
  • Base value can't be blank
  • Base value is not a number
  • Base value must be an integer
  • Base value must be greater than or equal to 1
  • Base value must be less than or equal to 10000000
quantity Quantity of product in parcel Integer
  • Quantity can't be blank
  • Quantity is not a number
  • Quantity must be greater than or equal to 1
  • Quantity must be less than or equal to 15000
weight Declared weight for total quantity of this product Integer Must be in grams. Example: 6 pieces in the parcel, each piece weighs 1.5kg. weight should be 6 pieces * 1.5kg per piece * 1000 grams per kg = 9000 grams
  • Weight can't be blank
  • Weight must be between 1g and 30kg
  • Weight sum of weights too high
country_of_origin Country in which product was manufactured String Must be a 2-letter ISO 3166-2 code, e.g. CN
  • Country of origin can't be blank
  • Country of origin must be an ISO 3166-2 code, one of AU, GB, CN, IN, LK, TR or US
commercial_ref Commercial reference of a product that allows to identify it, could be SKU, SKC, MPN, UPC, ISBN, ASIN etc. String Mandatory for Sale B2C DE.
  • Commercial ref can't be blank
marketplace_url URL linking to product page String Mandatory for all types except Sale B2C and Sale C2C. Needs to start with http:// or https://
  • Marketplace URL can't be blank
client_ref Reference of your choice String Optional.
material Main material that product is made from String Optional. This field helps us to review the provided HS code.
  • Material is too long (maximum is 50 characters)
  • Material must not contain multiple lines
  • Material must only contain latin or printable ASCII characters
atr_number ATR Number String Optional. This field is applicable only when country of origin is Turkey.
  • ATR number must be blank
long_haul_type Mode of transport of parcel String Optional. This field is mandatory for BE Marketplace 5, must be absent for the other types of declaration.
  • Long haul type not allowed for this type of declaration
  • Long haul type can't be blank
  • Long haul type has an invalid value
fulfiller Online marketplace operator or fulfillment company String Optional. Slug value of the fulfiller (e.g. amazon ). This field is mandatory for BE Marketplace 5, must be absent for the other types of declaration.
  • Fulfiller can't be blank
  • Fulfiller is inactive

Generic errors

In addition to specific errors at the attribute level, the following errors may occur at the base level of the declaration, because they are not tied to one specific attribute, depend on multiple attributes or depend on additional registrations.

  • VAT number and POA number must be used together
  • Sum of base values too high
  • Representative EORI number and Representative POA number must be used together
  • Direct representation not allowed
  • Representation registration has not been approved or is unknown
  • Required type of customs clearance not supported ( the system was unable to find any clearance methods supported by ViaEurope that match the provided data )

    • Example

    Request

    {
  "type": "sale_b2c_4",
  "declaration_country": "NL",
  "country_of_export": "CN",
  "force_general_clearance": null,
  "origin_client_ref": "FOOBAR",
  "consignee": {
    "name1": "ViaEurope BV",
    "street": "Pudongweg 21",
    "zip": "1437EM",
    "country": "NL",
    "city": "Rozenburg"
  },
  "exporter": {
    "name1": "Exporter name",
    "street": "Exporter street",
    "zip": "510620",
    "city": "Guangzhou",
    "country": "CN"
  },
  "products": [
    {
      "description": "Carpenter Hammer",
      "taric": "1234567890",
      "base_value": 36120,
      "quantity": 10,
      "weight": 6000,
      "country_of_origin": "CN",
      "client_ref": "ABC-123",
      "marketplace_url": "http://www.amazon.de/dp/B000VCZU8O"
    },
    {
      "description": "Beard Trimmer",
      "taric": "1234567890",
      "base_value": 17990,
      "quantity": 10,
      "weight": 10000,
      "country_of_origin": "CN",
      "client_ref": "DEF-789",
      "marketplace_url": "https://www.amazon.co.uk/dp/B07BHXZLZR"
    }
  ]
}

    Cancel declaration

    Will cancel the parcel's most recent declaration. This cannot be undone! This endpoint has no response, other than a HTTP status code to indicate success or failure, along with possible errors.

    Endpoint

    [DELETE] /v4/parcels/{client_ref}/declaration