Classification readiness

The customsDescriptionValidate mutation checks whether an item's information is sufficient to confidently assign a 6-digit HS code, before classification runs. It returns a readiness status that you apply your own policy to—proceed to classify, warn, ask the shopper or merchant for more detail, or reject the item.

It is a pre-flight check, not a classification: customsDescriptionValidate does not classify the item and does not return an HS code. Use it to catch thin or unusable descriptions upfront so that the descriptions you eventually send to Classify produce accurate, assumption-free results.

Readiness checking is just one use, though. Because the same item data drives Zonos's customs-description and classification services, this mutation is the entry point to a broader Customs Description workflow—gating data quality, then generating a compliant customs description from the item. See More than a classification gate below.

Readiness statuses 

Every validation returns one status. The status is advisory—your integration decides the consequence of each value.

When the status is INCOMPLETE, the missingAttributes field returns the missing attribute(s) as a short phrase (e.g. "fiber content" or "material, construction") that is suitable for composing a user-facing message. It is null for any other status.

Validate an item via API 

Provide the item fields directly—at least one descriptive field is required. The example below validates an item whose name and description identify it as a t-shirt but omit the fiber content needed to classify it, so the mutation returns INCOMPLETE.

Input fields

Provide either existingItemId or the item fields directly—at least one descriptive field is required.

Validate an existing item 

If the item already exists in Zonos, pass its ID as existingItemId instead of re-sending every field. The stored item's fields are used as the basis for validation, and any fields you also supply in the same input override the stored values—useful for testing whether an edit would make a thin item classification-ready.

The response content echoes the item data that was validated, with existingItemId resolved, so each stored CustomsDescriptionValidation is self-describing.

More than a classification gate 

Because the readiness status is advisory, the same check feeds more than one workflow—it isn't only about deciding whether to classify. customsDescriptionValidate evaluates the same item data that Zonos's classification and customs-description services consume, which makes it a natural first step in a broader Customs Description workflow:

• Data-quality gate — Surface thin or unusable item information at the point of entry (in a PIM, catalog import, or checkout) and prompt for exactly what's missing using missingAttributes, before that data flows downstream.
• Generate a customs description — Once an item is READY, hand the same data to the customsDescriptionsCreate mutation to have Zonos generate a concise, customs- and ICS2-compliant customs description from the item—optionally requesting an HS code in the same call. Validating readiness first means the generated description is built from complete information rather than assumptions.
• Classify with confidence — Proceed to Classify knowing the description is rich enough to assign an accurate 6-digit HS code with no guesswork.

A typical end-to-end flow is: validate readiness → collect any missingAttributes → generate a compliant customs description (and HS code) → classify or file.