DOCS

Customs Description Validation

Check whether an item's description is complete enough to confidently classify it — before you classify.

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.

Three 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.
  • sessionId — link follow-up validations of the same item so customers aren't asked the same question twice. See Sessions.

Readiness statuses 

The status field returns one of four values.

Status↕What it means↕Recommended action↕
READYThe information is sufficient to confidently determine the HS code with no assumptions. clarifications is empty.Proceed to classify.
INCOMPLETEThe item is identifiable, but choosing among the plausible HS subheadings would require assuming an unstated detail.Ask the customer for the detail in clarifications, then validate or classify again.
READY_TO_SUBHEADINGThe six-digit subheading is confidently determined, but a detail is still missing to pick the correct country-specific tariff line. Only possible when shipToCountry was supplied.Optionally collect the extra detail for precise duties, or proceed at the subheading level.
UNRECOGNIZABLEThe text doesn't establish what the item fundamentally is — for example an empty value, a bare SKU or internal code, or gibberish.Ask the customer to re-enter the item.

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.

Sessions 

Every validation returns a sessionId. When the customer updates the item in response to the clarifications, validate again and pass that sessionId back with the complete, updated item information — not just the new detail.

Within a session, validation remembers what it has already asked. A question is not repeated, even if the customer skipped it or only partly answered it, so the customer is never stuck answering the same prompt in a loop. If every remaining question has already been asked, the status returns READY so the item can move forward.

1{
2 "input": {
3 "name": "Women's blouse",
4 "description": "long-sleeve blouse, woven",
5 "sessionId": "customs_description_validation_0ryft0yp0f5fg"
6 }
7}

In this follow-up to the blouse example, the customer added that the blouse is woven but not its material. The material question was already asked in this session, so it isn't asked again and the item proceeds as READY.

Keep these rules in mind:

  • Omit sessionId on the first validation of an item to start a new session.
  • Sessions belong to the calling organization and use one destination country. Changing shipToCountry starts a new session, so always use the sessionId from the latest response.
  • Start a new session for each distinct item.

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.

1mutation CustomsDescriptionValidate(
2$input: CustomsDescriptionValidationInput!
3) {
4 customsDescriptionValidate(input: $input) {
5 status
6 clarifications
7 sessionId
8 content {
9 name
10 description
11 material
12 categories
13 }
14 }
15}

In the example above, the item is clearly identifiable as a blouse, but apparel is classified partly by material and construction — 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 those details are added, the same item validates as READY.

GraphQL API ReferenceTypes, inputs, and operations used in this guide
Book a demo

Was this page helpful?


Get support·Legal docs·© 2026 Zonos