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.
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.
The information is sufficient to confidently determine the HS code with no assumptions. clarifications is empty.
Proceed to classify.
INCOMPLETE
The 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_SUBHEADING
The 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.
UNRECOGNIZABLE
The text doesn't establish what the item fundamentally is — for example an empty value, a bare SKU or internal code, or gibberish.
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.
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.
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.
Use the customsDescriptionValidate mutation. Provide the item's fields directly, or reference a stored item with existingItemId. At minimum, include one descriptive field.
1mutationCustomsDescriptionValidate(
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.
See a READY example
A description that already carries the decisive attributes validates as READY with no clarifications.
1{
2"input":{
3"name":"Men's crew-neck t-shirt",
4"material":"100% combed cotton, knit",
5"categories":[
6"Apparel",
7"Tops"
8]
9}
10}
See a country-specific example
Adding shipToCountry checks readiness down to the destination's tariff line. Here the six-digit subheading is already determined, so the status is READY_TO_SUBHEADING and the clarifications describe what's still needed to pick the exact tariff line.
1{
2"input":{
3"name":"Pullover sweater",
4"material":"100% cotton, knit",
5"categories":[
6"Apparel",
7"Tops"
8],
9"shipToCountry":"US"
10}
11}
GraphQL API ReferenceTypes, inputs, and operations used in this guide
Customs Description Validation
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, andcategories. 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
statusthat tells you how ready the description is, and — when something is missing — aclarificationslist that tells you exactly what to ask for.Validation does not classify the item and does not return an HS code. The
statusis 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
statusfield returns one of four values.READYclarificationsis empty.INCOMPLETEclarifications, then validate or classify again.READY_TO_SUBHEADINGshipToCountrywas supplied.UNRECOGNIZABLEClarifications
Whenever the status is not
READY, theclarificationslist 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,clarificationsis empty.Sessions
Every validation returns a
sessionId. When the customer updates the item in response to the clarifications, validate again and pass thatsessionIdback 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
READYso the item can move forward.{"input": {"name": "Women's blouse","description": "long-sleeve blouse, woven","sessionId": "customs_description_validation_0ryft0yp0f5fg"}}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:
sessionIdon the first validation of an item to start a new session.shipToCountrystarts a new session, so always use thesessionIdfrom the latest response.Validate a customs description
Use the
customsDescriptionValidatemutation. Provide the item's fields directly, or reference a stored item withexistingItemId. At minimum, include one descriptive field.mutation CustomsDescriptionValidate($input: CustomsDescriptionValidationInput!) {customsDescriptionValidate(input: $input) {statusclarificationssessionIdcontent {namedescriptionmaterialcategories}}}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, andclarificationstells you exactly what to ask the customer for. Once those details are added, the same item validates asREADY.See a READY example
A description that already carries the decisive attributes validates as
READYwith no clarifications.{"input": {"name": "Men's crew-neck t-shirt","material": "100% combed cotton, knit","categories": ["Apparel","Tops"]}}See a country-specific example
Adding
shipToCountrychecks readiness down to the destination's tariff line. Here the six-digit subheading is already determined, so the status isREADY_TO_SUBHEADINGand theclarificationsdescribe what's still needed to pick the exact tariff line.{"input": {"name": "Pullover sweater","material": "100% cotton, knit","categories": ["Apparel","Tops"],"shipToCountry": "US"}}CustomsDescriptionValidationInput
customsDescriptionValidate
Was this page helpful?