TABLE OF CONTENTS
Customs Article Master Data endpoint
The article master data endpoint is used by customers - subject to prior agreement - for the following purposes:
- Tariff clasification: To submit article information so that we can review the data and assign appropriate descriptions and tariff numbers.
- Data enrichment: To enrich shipment skus (articles) with the master data record on a transactional basis (when customs shipment is created), ensuring consistent and accruate information for customs clearance.
Guidelines for submitting articles
- The POST Customs Article Master Data endpoint is used to create new articles or update existing ones.
- When submitting articles, you can submit data for an article per customs coutry where this article is sold (CH, GB, NO). These are submitted as "directions" in the request.
- For example: If an article is shippped from Germany (DE) to Switzerland (CH), you would submit a direction DE to CH.
- Note: Please do not submit reverse directions (e.g. CH to DE in this example). Return flows are handled intenally and do not require separate submissions.
- In our system an article is uniquely identified by the combination of article_id, upc_code and country_of_origin.
- Important: If you include preferential_code, net_value, sales_value or vat_tariff in the request , these values will overwrite the corresponding fields in the shipment skus submitted daily. If this data varies per shipment or you do not want it to be updated automatically, please omit these fields from the request.
| Parameter | M/O | Type | Example | Description |
|---|---|---|---|---|
| article_id | m | string | "9988776655" | Internal article or product reference number. |
| upc_code | m | string | "116800711680" | The UPC or EAN code of the aricle. This value must be present on the article and preferably scannable. Every variation of your product will need its own UPC/EAN. |
country_of_origin | m | string | "DE" | ISO-2 country code for the country of origin of the article (where it was produced). |
| url | m | string | "https://www.bergfreunde.de/ patagonia-womens-regenerative-organic-cotton-tee-t-shirt" | The product page URL. |
| product_material_composition | m | string | "100% Baumwolle" | Material which the product consists of. |
| category | m | string | "Outdoor Bekleidung/Shirts, Hemden & Longsleeves/T-Shirts." | The category keywords of the article to narrow down the selection. |
| gender | o | enum | "female" | Enum: "male" | "female" | "unisex" Mandatory to be provided when the gender can be identified on the product. If the product has no gender, please do not submit this field. |
| brand | o | string | "Patagonia" | The brand of the article. |
| color | o | string | "Plum grey" | The color of the article. |
| image_url | o | string | "https://www.bergfreunde.de/ patagonia-womens-regenerative-organic-cotton-tee-t-shirt/#galleryid-1.pictureid-1"" | The product image URL. |
| language_code | o | string | "de" | The ISO 693-1 language in which the product page is. The language code must be provided in sentence case letters. |
| Directions object as array | ||||
| departure_country | m | string | "DE" | The departure country in ISO2 format. |
| arrival_country | m | string | "CH" | The arrival country in ISO2 format. |
| departure_country_description | m | string | "T-Shirt gewirkt aus baumwolle" | Description of the article in language of departure country. The description must include (1) article, (2) material, (3) what is the article used for, (4) product name. |
| departure_country_language | o | string | "de" | The ISO 693-1 code of the official language of the departure country (the language in which the article description is provided). The language code must be provided in sentence case letters. |
| departure_country_tariff_number | o | string | "61091000" | Harmonized Tariff/Commodity code of the article according to the legislation in the departure country. For shipments departing from EU, CH or arriving to CH the code is 8 digits. |
| arrival_country_description | o | string | "T-Shirt gewirkt aus baumwolle" | Description of the article in language of arrival country. The description must include (1) article, (2) material, (3) what is the article used for, (4) product name. If arrival country is GB we recommend providing this description. |
| arrival_country_language | o | string | "de" | The ISO 693-1 code of the official language of the arrival country (the language in whichthe article description is provided). The language code must be providedd in sentence case letters. Note: If an article is being sold in CH, the language value should be "de". |
| arrival_country_tariff_number | o | string | "61091000" | Harmonized Tariff/Commodity code of the article according to the legislation in the arrival country. For shipments arriving to GB the code is 10 digits, arriving to CH or NO the code is 8 digits. |
| preferential_code | o | string | "1" | Customs code indicating duty preference type (1 = preferential goods or 2 = non-preferential goods). Preferential goods are goods that are produced in the EU where the majority of materials originate from the EU. If customers declare preferential goods, they must have a preferential calculation in place. Please note that most customers do not have this calculation in place. |
| weight | o | number | 115 | Weight of an individual article. |
| weight_unit | o | string | "G" | The unit of the weight for the article: K = kilos, G = grams. |
| net_value | o | number | 39.95 | Monetary value of an individual article without VAT. |
| sales_value | o | number | 43.026 | Monetary value of an individual article including VAT. |
| vat_tariff | o | string | "8.1" | The percentage of related VAT tariff in the arrival country. Values submitted here will be used to update shipments submitted in future. |
Legend: m = mandatory, o = optional.
Request example
{
"article_id": "9988776655",
"upc_code": "116800711680",
"url": "https://www.bergfreunde.de/patagonia-womens-regenerative-organic-cotton-tee-t-shirt",
"product_material_composition": "100% Baumwolle",
"category": "Outdoor Bekleidung/Shirts, Hemden & Longsleeves/T-Shirts.",
"country_of_origin": "DE",
"gender": "Female",
"brand": "Patagonia",
"color": "Plum grey",
"image_url": "https://www.bergfreunde.de/patagonia-womens-regenerative-organic-cotton-tee-t-shirt/#galleryid-1.pictureid-1",
"language_code": "de",
"directions": [
{
"departure_country": "DE",
"arrival_country": "CH",
"departure_country_description": "T-Shirt gewirkt aus Baumwolle",
"departure_country_language": "de",
"preferential_code": "1",
"departure_country_tariff_number": "61091000",
"arrival_country_description": "T-Shirt gewirkt aus Baumwolle",
"arrival_country_language": "de",
"arrival_country_tariff_number": "61091000",
"weight": 115,
"weight_unit": "G",
"net_value": 39.95,
"sales_value": 43.026,
"vat_tariff": "8.1"
},
{
"departure_country": "DE",
"arrival_country": "NO",
"departure_country_description": "T-Shirt gewirkt aus Baumwolle",
"departure_country_language": "de",
"preferential_code": "1",
"departure_country_tariff_number": "61091000",
"arrival_country_description": "T-skjorte i strikket bomull",
"arrival_country_language": "no",
"arrival_country_tariff_number": "61091000",
"weight": 115,
"weight_unit": "G",
"net_value": 39.95,
"sales_value": 43.026,
"vat_tariff": "8.1"
}
]
}