Avalara Item Classification automates the complex process of determining HS codes, taking into consideration country, product attributes, and other factors.

Core capabilities

Apply Avalara-maintained tax rules and rates tailored to your product category and jurisdictions.

Industry-specific logic

Support tiered pricing, bundled offerings, exemptions, and multi-jurisdiction calculations without custom engines.

Complex scenarios

Stay current with evolving requirements through regularly updated content and configuration options.

Regulatory alignment

Integrate with billing, ERP, and custom apps using REST APIs built for high-volume transaction processing.

Operational scale

Use API documentation, integration checklists, and environment setup guides linked from each product below. Provisioning and access details depend on your Avalara products and onboarding path.

Getting started

Avalara APIs provide REST interfaces for billing, subscription, ERP, and custom applications. They support scalable tax determination and high-volume processing so you can embed compliance into your existing workflows.

How it integrates

What Tariff Code Classification solves

When to use Tariff Code Classification

Tariff Code Classification

Get Started

Automated Tariff Code Classification assigns HS and HTS tariff codes to products at scale using predefined logic and classification models. It helps businesses standardize product classification across large catalogs without manual intervention.

Automatically classify large product catalogs using standardized logic.

High-volume classification

Apply consistent tariff codes across systems and transactions.

Consistent code assignment

Reduce reliance on manual classification workflows.

Reduced manual effort

Support growing catalogs and global expansion.

Scalable classification workflows

Integrate classification workflows through APIs by submitting product attributes and retrieving assigned tariff codes. Setup typically includes mapping product catalog data and configuring classification rules within your system.

Integrate via REST APIs to submit product descriptions and receive tariff code assignments in real time.

Automated Tariff Code Classification

Self-Serve Tariff Code Classification allows users to manually classify products by entering product details and attributes. It is designed for interactive classification workflows when automation is not required.

This guide describes the steps you should follow to integrate ClassyVue into your system.

ClassyVue integration guide

Classify products using descriptions and attributes.

Interactive classification

Flexible input handling

User-controlled decisions

Enable interactive classification through APIs that accept product descriptions and return tariff code suggestions. Implementation requires passing product data and handling user-driven selection workflows.

Use the self-serve interface directly or integrate via APIs for a hybrid classification approach.

Self-Serve Tariff Code Classification

Managed and Premium Tariff Code Classification provide expert-led and hybrid classification services to support accurate tariff code assignment for products. These solutions are designed for businesses that require high confidence in classification, especially for complex or compliance-sensitive scenarios.

Leverage specialists to assign and validate tariff codes for accuracy and compliance.

Expert-led classification

Combine automated classification with expert review to support high-confidence results.

Hybrid classification model

Ensure classification outputs meet regulatory requirements and support audit workflows.

Compliance and audit support

Support classification for products with complex attributes, regulatory requirements, or high-risk profiles.

Complex product handling

Get started by onboarding products into classification workflows.

You can integrate APIs to submit product data and retrieve validated tariff codes, with support for automated processing and expert review.

Submit product data through APIs or batch uploads and receive expert-assigned tariff codes with supporting documentation.

Managed and Premium Tariff Code Classification

Avalara Trade Compliance helps businesses manage regulatory requirements for cross-border transactions. It supports compliance with trade rules, restrictions, and regulatory obligations.

Apply trade compliance rules across jurisdictions.

Regulatory rule management

Risk reduction

Help ensure transactions meet regulatory requirements.

Cross-border control

Integrate compliance checks into transaction workflows using APIs to validate cross-border transactions against regulatory requirements. Setup includes configuring jurisdiction rules and adding compliance checks to order processing workflows.

Integrate via REST APIs to screen transactions and retrieve compliance status in real time.

Avalara Trade Compliance

The Trade and Tariff Library provides access to global tariff schedules, duty rates, and trade data required for cross-border compliance and decision-making.

Access global tariff schedules and duty rate information.

Centralized tariff data

Stay aligned with changing trade regulations.

Up-to-date trade data

Support classification and compliance workflows.

Data-driven decisions

Access tariff and trade data through APIs by querying country, product, and classification inputs. Integration involves incorporating tariff data retrieval into classification, calculation, or compliance workflows.

Query tariff data and duty rates via REST APIs to embed trade data into pricing, compliance, and logistics workflows.

Avalara Trade and Tariff Library

Comma-separated list of supported `avalara-version` dates (most recent first).

The `avalara-version` the server honoured for this response.

For single-item submissions, points at the canonical GET endpoint for
the newly-created classification. For bulk submissions, points at the
first item's GET URL; callers should iterate
`items[].classifications[].id` for the rest.


Requests remaining in the current window.

Unix epoch (seconds) when the window resets.

Seconds the client should wait before retrying (RFC 7231).

Dated version of the contract the caller is pinning to (`YYYY-MM-DD`).
Discoverable via `OPTIONS` on the same path (`avalara-supported-versions`
response header). Unsupported dates return 422; sunset dates return 410.


avalara-version

companyId

Context

customerId

returnIcAccountId

Standard Avalara client-identification / telemetry header. Optional free-form string
identifying the calling application (app name, version, machine, environment), e.g.
`AppName; 1.0; MyMachine; PRD`. Used for support and usage analytics only; it does not
affect request processing.


X-Avalara-Client

Allowed methods and contract versions for this path. Used for CORS
pre-flight and version discovery; the body is intentionally empty.


Rate limit exceeded. Honour the `Retry-After` header before retrying.
Body uses the `AvaTaxError` envelope with `RateLimitExceeded`.


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

Returned for:
- Gateway / OAuth failures (**401**) before the controller runs.
- **POST** `/{companyId}/classifications` HTTP-level failures: **403**, **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`.


This service or operation is not authorized for this account or user.

Groups content-level changes by country for a given HS root.

Lists the content-level changes for this country.

Identifies the country associated with the changes, in ISO 3166-1 alpha-2 format.

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.


Reverse-mapped from the legacy uppercase activity (`HS_FULL` -> `hsFull`, `ECCN` -> `eccn`, etc.).

Suppressed when the resolved customer's `confidenceFlag` is off.

Suppressed alongside `confidence` for customers without the confidence flag.

Present for `export` and `eccn`, read from the record's
`country_of_export` parameter (not from `countryOfDestination`).


Present for `coo` — the resolved country of origin, read from the
record's `coo` parameter.


Export-control code (e.g. `5A001.a`) returned for `eccn` instead of
`hsCode`, read from the item's `eccn_code` parameter
(`product.eccn_code`). Absent until the classification has been worked.


Final HS code; present once `status == "classified"` for `hsFull` / `hs6`.
Never present for `eccn` — see `eccnCode`.


Composite ID; same value the POST response surfaces under `items[].classifications[].id`.

Suppressed unless `status == "classified"` (V1 parity).

Reverse-mapped from the legacy status using the same heuristics as the POST builder.

10mm Combination Wrench

**`eccn`** (export-control classification) is a standalone activity, not a
variant of `export`. It has two extra requirements and one routing quirk:

- `countryOfDestination` is **required** (reused as the licence-determination
  jurisdiction; there is no separate ECCN jurisdiction field). Omitting it
  returns `422` / `COD_REQUIRED`.
- `item.countryOfExport` is **required per item** — it selects the control list
  (US → CCL under EAR, EU → dual-use list), so without it there is no scheme to
  resolve a code in. Omitting it returns `422` / `COE_REQUIRED_FOR_ECCN`.
- ECCN has no auto-classifier. An ECCN-primary request is **re-routed to the
  managed pipeline for every `classificationType`**, including `autoPro` and
  `autoEssentials` — it is not rejected. The response echoes the caller's
  original `classificationType`.

`hsCodeTest` is ignored for `eccn` (a test HS code is meaningless for an
export-control result and must not put an `hsCode` back on it).


Capped at 10 per request (configurable via
unify.max.countries.of.destination). Exceeding returns 413.

Required when `classifications` includes `hsFull`, `hs6` or `eccn`
(`422` / `COD_REQUIRED`). For `eccn` it is the licence-determination
jurisdiction, not the country the code is resolved against — that is
`item.countryOfExport`.


**Sandbox / integration use only.** Pre-supplied HS code per
country of destination. When present, the server treats the
listed code as the final classification for that COD and
bypasses all classification logic (no Indix / HSAC call).
Strictly capped to 20 characters per value.

Independent of `classificationType`, every COD listed in
`hsCodeTest` is processed via the managed pipeline. When the
caller asked for an auto type and supplied `hsCodeTest` for
every entry in `countryOfDestination`, the entire request is
re-routed to managed. Partial coverage splits the request:
covered CODs run through managed, the rest through the
requested auto path.

Covered CODs surface in the response as
`status: "classified"`, `hsCode: "<test value>"`,
`confidence: "test"`. Uncovered CODs follow the regular auto
response shape. The response's `classificationType` echoes
the original caller value (re-routing is internal).


Bulk shape. Capped at 10 per request (configurable via
unify.max.items.per.request). Exceeding returns 413.


Please provide a value for field countryOfExport.

Per-COD compliance payload returned by the Quoting service. Populated only
when `compliance` is in `classifications` *and* an HS code is available
for the COD (auto path: Indix prediction; managed path:
caller-supplied `providedHsCodes`). Mutually exclusive with
`complianceError`. Item shape mirrors
`com.avalara.xb.classification.views.Compliance` (Quoting response).


Set when the unify compliance gate skipped the Quoting call because the item
is missing a field Quoting requires (today: `countryOfExport`). Wire
shape is identical to Quoting's own `ValueRequiredError` payload
(`{ details: [{ code, number, message, description, helpLink, severity }] }`).
Mutually exclusive with `compliance`; the classification itself is
unaffected.


Present for `export` and for `eccn`. An ECCN result is **keyed by the
exporting country** — `countryOfExport` selects the control list, so it
identifies the result the way `countryOfDestination` does for `hsFull`,
and the composite `id` carries it as the trailing country segment
(e.g. `2-1000-1651708-WRENCH-10MM-ECCN-DE`). Null when the request
carried no item.


Present for `coo` — the resolved ISO-2 country of origin. Null on a POST
response (the classifier has not run; `item.countryOfOrigin` is only an
input hint); populated on GET once classified.


Export-control code (e.g. `5A001.a`) for `eccn` results, in place of
`hsCode`.

**Null on a POST response.** ECCN is managed-only with no auto-classifier,
so no code exists at submission time — an ECCN POST result carries no code
in either field, the same as `coo`. Fetch the classification by `id` once
it has been worked; `GET .../classifications/{id}` fills this in from the
item's `eccn_code` parameter.


Never present for `eccn`. An export-control result must not carry an HS
code — the underlying record can hold one (mixed request, reclassify,
pre-existing value) and surfacing it here would present tariff data as
the ECCN answer.


Two characters ISO 3166 code identifying the country

is given request parameter has ADD (Anti-Dumping Duty) rates.

is given request parameter has CVD(Countervailing Duty) rates.

is given request parameter PGA restrictions for countryOfImport.

is given request parameter have restrictions for countryOfImport.

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`.


Optional top-level summary code. Omitted by the unify gate today.

Optional top-level summary message. Omitted by the unify gate today.

Optional context tag. Omitted by the unify gate today.

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.


Describes a single content-level nomenclature change.

Describes the nature of the content-level change. The content-level payload uses `changeType` with `INVALID_CODE` for a retired code, whereas the item-level payload uses `eventType` with `INVALID_HSCODE`.

Provides the effective-from date as an integer in YYYYMMDD format.

Provides the effective-to date as an integer in YYYYMMDD format. This field is `null` when the code does not have an expiry date.

Provides the HS code affected by the change.

Provides the description of the HS code after the change. This field is `null` when not applicable.

Provides the description of the HS code before the change. This field is `null` when not applicable.

Defines the content-level general nomenclature notification. The changes use a nested structure, grouped by HS root and country, following the path `changes[] -> changedCountries[] -> changes[]`.

Lists the nomenclature changes grouped by HS root.

Identifies the Avalara customer account associated with this notification.

Provides the unique identifier for this notification.

This value is always `NOMENCLATURE_CHANGES` for this payload.

Provides a high-level summary of the changes included in this notification.

Provides the date and time the notification was sent, in ISO-8601 UTC format.

Provides a high-level summary of the content-level nomenclature changes included in the notification.

Lists the affected HS chapters, represented by the first 2 digits of each root.

Lists the countries affected by the changes, in ISO 3166-1 alpha-2 format.

Provides the total number of individual changes included in the notification.

Provides the total number of HS roots affected by the changes.

the name of the product that need to ship

`multipart/form-data` body for the document-upload variant of this endpoint. Submit a PDF
and/or image(s); the service reads them into classification object(s) and classifies them.
At least one of `pdf`, `images`, `text`, `imageUrl`, or `url` must be supplied. The
classification-intent fields (`classificationType`, `classifications`, `countryOfDestination`)
are applied to every product extracted from the document(s). Files are validated for type,
size (≤ 25 MB/file, ≤ 50 MB total, ≤ 10 files), page count (≤ 50), readability, encryption,
and image quality before extraction.


Classification tier applied to every extracted product.

Comma-separated classification activities applied to every extracted product — e.g.
`hsFull` or `hsFull,compliance`. Allowed: `hsFull`, `hs6`, `export`, `eccn`,
`compliance`, `coo`, `premium`. Including `eccn` additionally requires
`countryOfDestination` and `countryOfExport`.


Comma-separated ISO 3166-1 alpha-2 destination country codes applied to every extracted
product — e.g. `US` or `US,CA`. Required when `classifications` includes
`hsFull`, `hs6` or `eccn`.


ISO 3166-1 alpha-2 country-of-export hint. Applied to every extracted
product, and **required** when `classifications` includes `eccn` — the
per-item rule (`COE_REQUIRED_FOR_ECCN`) is evaluated against the
extracted items, so an ECCN upload without it fails validation after
extraction.


URL of a product image to read, instead of or in addition to an uploaded file.

One or more image files (PNG / JPG / JPEG). Repeat the field to send several.

When true, classify using export (Schedule B) codes.

Raw product text/description (alternative or supplement to a file).

Basis for duty calculation (e.g., PRICE, QUANTITY, CIF)

Indicates if Free Trade Agreement rates apply

Provides the duty rate after the change. This field is omitted for a `DUTY_REMOVED` event.

Lists the countries this duty change applies to, resolved from the tariff system. This field replaces the former single duty `countryCode`.

Provides the date and time when the duty change takes effect, in ISO-8601 format.

Provides the date and time when the duty rate stops being effective, in ISO-8601 format. This field is `null` when the duty rate does not have an expiry date.

Identifies the type of duty change. The value is `DUTY_RATE_CHANGE`, `DUTY_ADDED`, `DUTY_REMOVED`, or `FTA_UPDATE`.

Provides the HS code the duty applies to.

Provides the duty rate before the change. This field is omitted for a `DUTY_ADDED` event.

Provides a human-readable label for the duty rate.

Provides the tariff system the duty change belongs to, for example, EU.

Provides the trade group or FTA name for FTA changes.

Defines the duty rate notification. The payload uses a flat `changes[]` envelope where each change is based on the HS code and rate and does not include catalog items. The rate is expressed as nested `previous` and `current` objects.

Lists the duty rate changes included in this notification.

Provides the count of changes grouped by `eventType`.

Provides the date and time when the underlying changes were detected, in ISO-8601 UTC format. This field is omitted when the detection time is unknown.

Provides the total number of duty rate changes included in this notification.

Describes 1 side, either the previous or current value, of a duty rate.

Provides the currency for specific or compound duties. This field is omitted for ad-valorem percent rates.

Provides the unit the rate is calculated on, for example, PERCENT or a per-unit measure.

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 `403` / `413` / `422` / `503` / `500` on `POST .../classifications`;
those responses use `AvaTaxError`. Gateway `401` also uses `AvaTaxError`.


Name of the error. Refer to Error Codes section for a list of accepted values.

A more detailed description of the problem referenced by this error message, suitable for display in the contents area of an alert box.

Concise summary of the message, suitable for display in the caption of an alert box.

Unique ID number referring to this error or message.

Item the message refers to, if applicable. This is used to indicate a missing or incorrect value.

Severity of the message`:`  Success, Warning, Error and Exception.

Short one-line message to summarize what went wrong

What object or service caused the error? (Unknown, HttpRequest, HttpRequestHeaders, IncorrectData)

hs_code_test

price

weight

The required classification activity for the request. Accepted values are: HS_FULL : full HS code classification (country specific). This is the default activity if no value is specified in the request. HS6: 6 digits HS code classification

If the information provided in the request is not enough, an accurately classification might not be possible. In this case, the assumption made for classification will be returned in this field.

This is a detailed description of the assumptions made in order to classify an item when information provided in the request is not enough (e.g. similar product URL, product number or anything which can be used as identifier behind the classification logic).

Single country of destination code (ISO 3166-1 alpha-2).
Must be a valid country code supported by the system.


Multiple countries of destination codes (ISO 3166-1 alpha-2).
- Must be valid country codes supported by the system
- Invalid country codes will be included in the invalidCODs array
- At least one valid country code is required


This is the HS classification result. It’ll be returned in the body for GetHSClassification method.

The id of the HS classification request. This id is created by CreateHSClassificationRequest and returned in the response.

List of invalid country codes that could not be processed

Alternative to `item` for submitting **multiple products** in a single request. Provide either `item` (one product) or `items` (many) - not both. Each product is classified independently and the response is a **JSON array** (HTTP 207) with one element per item, in request order; each element is a classification result or a per-item error object.

Alternative HS codes that could apply to this item, when available. This field is only included when the broker parameter is set to "true" and there are alternative HS codes available. Provided as a stringified JSON array.

Indicates whether the product information was updated during classification.

This value will be returned by getHSClassification method only if an item cannot be classified (status=CANNOT_BE_CLASSIFIED). It contains a detailed description of the issue. It’ll be ignored if it’s provided in the request.

This value is returned by get HS Classification method. It’ll be ignored if it’s provided in the request.

List of valid country codes that were successfully processed

Tariff Code Classification

ItemChangeNotification