Tariff Code Classification

OverviewAPI
Version v2
Classifications
CreateHSClassificationRequest
GetHSClassification
HSCodeValidationRequest
HSCodeVerificationRequest
WebhookCallback

Avalara Item Classification API Models

ModelSummary

AvaTax-style error envelope { "error": { "code", "target", "details"[] } }.

Returned for:

  • Gateway / OAuth failures (401) before the controller runs.
  • POST /{companyId}/classifications HTTP-level failures: 402, 413, 422, 503, 500 (and downstream AvaTaxException bodies when mapped by the controller).
  • GET .../classifications/{id} 404, 422, 500 (mirrors legacy V1).

Nested per-item / per-COD errors inside a 207 ClassificationResponse still use the flat Error schema on the embedded error fields.

Use error.code plus error.details[].number to branch programmatically. Common numbers include 31 / 34 / 37 (auth), 5 (ValueRequiredError), 50 (UnhandledException), 70 (ModelStateInvalid), 3011 (MtccPlusNotProvisioned), 3015 (EntitlementRequired), 3016 (PayloadTooLarge), 3008 (RetryRequest), and values from ClassificationError.

—

Unify GET response - one classification record identified by the composite id, with the originating item embedded as item. Field projection is driven by the legacy classification record loaded from the underlying store (HSCT / ItemMaster / DW / parking lot, in priority order), not by parsing the ID. Fields beyond id / status are populated when the legacy record carries them. The embedded item reverses the legacy field-name flips (description -> title, summary -> description, itemGroup -> category); the _uncategorized sentinel is silently dropped.

—
—
—
—
—

Pure pass-through map. Anything the caller puts here is forwarded verbatim to the Quoting compliance service. The only locally validated fields are startDate / endDate (yyyy-MM-dd, end >= start). System-managed keys (id, hscode, countryOfImport, countryOfExport, countryOfManufacture, section232Parameters) are silently stripped before forwarding. Section 232 must be sent via item.section232[].

Compliance-enrichment error envelope returned on ClassificationResult.complianceError when the unify compliance gate short-circuited the Quoting call. Wire shape is identical to Quoting's own { details: [...] } validation-error payload, so unify callers can reuse the error handling they already wrote for direct AvaTax / Quoting calls. Mutually exclusive with ClassificationResult.compliance.

Single entry inside ComplianceError.details[]. 1:1 mirror of the AvaTax ErrorDetail shape (minus the legacy faultCode slot). The unify gate emits { code: "ValueRequiredError", number: 5 } for required-field violations - byte-for-byte identical to what Quoting returns when called directly.

—
—

Small { "code", "message" } object used only inside successful HTTP responses for nested failures — e.g. 207 payloads under items[].error or items[].classifications[].error when a single item or COD is rejected.

Not used for HTTP-level 402 / 413 / 422 / 503 / 500 on POST .../classifications; those responses use AvaTaxError. Gateway 401 also uses AvaTaxError.

—
—
—
—
—
—
—
—
—
—
—
—
—
—
—
—
—
—
—
—
—

The webhook callback payload that will be sent to the client's webhook endpoint when a classification is completed. Only clients who have specifically opted to receive webhook callbacks need to implement this endpoint. This is an optional feature for "Item Classification Without Storage" customers.

Authentication: The webhook callback supports two authentication methods:

  • Basic Authentication: Requires an API key configured in the Avalara system
  • OAuth: Requires an OAuth token endpoint to be configured in the Avalara system

Conditional Fields:

  • The possibleHsCodes field is only included when the broker parameter is set to "true" and there are alternative HS codes available

Retry Behavior: If the webhook call fails due to server connectivity issues, the system will automatically retry the call.