Customs Description Validation

Why a complete customs description matters 

Every cross-border shipment needs an HS code, and that code is only as good as the description it comes from. HS classification drives customs clearance and the calculation of duties and taxes, so the description on your commercial invoice has to say clearly what the item is and what it is made of.

When a description is vague or ambiguous, classification has to fill in the gaps with an assumption — and an assumed detail can lead to the wrong HS code. A wrong code means the wrong duties and taxes, and it raises the risk of clearance delays, fines, and other compliance problems.

Customs Description Validation lets you catch a weak description up front, at data-entry time, instead of discovering the problem after an item has already been classified on a guess. When something is missing, it tells you exactly what detail to ask the customer for — so you can fix the description before it ever reaches classification. When you're ready to generate the description itself, see Customs Description; to assign the HS code, see Classify.

How it works 

You submit the descriptive fields you have for an item — name, description, material, and categories. Validation judges whether that information is specific enough to land on a single HS code without assuming an unstated fact, such as fiber content, whether a fabric is knit or woven, or the item's intended use.

It returns a status that tells you how ready the description is, and — when something is missing — a clarifications list that tells you exactly what to ask for.

Validation does not classify the item and does not return an HS code. The status is advisory: you decide what to do with it based on your own policy — proceed to classify, warn, ask the customer for more detail, or reject the item.

Two optional inputs extend the check:

• existingItemId — validate an item you've already stored instead of passing its fields inline. Any fields you also supply override the stored values.
• shipToCountry — when provided, validation also checks whether the description is specific enough to pick the destination's country-specific tariff line, not just the six-digit HS subheading.

Readiness statuses 

The status field returns one of four values.

Clarifications 

Whenever the status is not READY, the clarifications list contains short, specific phrases describing what to add to the description — for example, "state the primary fiber content". These phrases are written to be shown directly to a customer, so a good pattern is to surface them at the point of data entry and prompt for the missing detail before moving on.

When the status is READY, clarifications is empty.

Validate a customs description 

Use the customsDescriptionValidate mutation. Provide the item's fields directly, or reference a stored item with existingItemId. At minimum, include one descriptive field.

In the example above, the item is clearly identifiable as a blouse, but apparel is classified partly by fiber content — so choosing the correct HS code would require an assumption. The status is INCOMPLETE, and clarifications tells you exactly what to ask the customer for. Once the primary fiber content is added, the same item validates as READY.

Retrieve past validations 

Every validation is stored, so you can look one up later or list your recent validations. Use the customsDescriptionValidation query to fetch a single result by id, or the customsDescriptionValidations query to page through your validations, most recent first.