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.

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

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.

the name of the product that need to ship

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

Indicates if Free Trade Agreement rates apply

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

The HS code to verify. Must be 6-12 digits, optionally followed by up to 2 letters.

Full classification response from the classification submission. Only present when verified=false and classification submission succeeds. Includes a 'failedVerificationCode' parameter in classificationParameters array.

Human-readable message about the verification result

Echo of the HS code that was submitted for verification

Whether the HS code was verified as appropriate for the product

The unique ID number of the company that owns this item.

A short description of the product. It’s also referred as product title or name.

A unique id generated by Avalara Classification System

A unique code representing this item. It’s recommended to use the SKU number.

Product category breadcrumbs. This is the full path to the category where item is included. Categories should be separated by ` > `.

Use the  parentCode to group product variants. Variants are a group of similar items that only differ from one another by product details like size, color, material, pattern, age group or size .

The system has predefined list of parameter names that are known and
processed accordingly (see enum).

Predefined parameters for a compliance enrichment
request include: compliance_flagging, country_of_export,
country_of_manufacture, manufacturer_name, compliance_start_date,
compliance_end_date. When `compliance_flagging` is set to `true`,
`country_of_export` is **required** (otherwise no compliance call
is made for that country of destination) and
`country_of_manufacture` + `manufacturer_name` are strongly
recommended for accurate duty, FTA, CVD/ADD and restrictions
lookups.

For a brokerage response, where classification provides an HS6 with
optional full HS codes for your brokers to select from requires the
broker parameter set to true. 

For a premium response, where classifications are returned with full
explanations of rationale require the
premium parameter set to true. 

The system also supports 
custom parameters. For custom parameters, the name is not predefined
and should be provided in the request.

Indicates if the rate applies under de minimis thresholds

Indicates whether this punitive rate should be applied **on top of** all other duty components (MFN, FTA).


Indicates whether the punitive rate is **compounded**, i.e. calculated as: rate + surchargeRate + (rate * surchargeRate)


Unit of measurement (e.g., percentage, kilogram, count)

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.


The ID of the company that owns this item.

Compliance information if compliance_flagging was enabled.

The country code for which the classification was performed.

The id of the HS classification request that was completed.

The unique item code (typically your SKU) that was classified.

Alternative HS codes that could apply to this item, when available.
This is provided as a stringified JSON array.


Explanation of the classification decision when available.

The status of the classification request.

If you're subscribed to the Avalara Item Classification service, these APIs 
 allow you to submit products for Item Classification and retrieve the 
 corresponding HS Codes.

 **Notes**:
 - Avalara Item Classification is a billable service. If the service is not 
 enabled, the API will not provide a response.
 - In the development environment (Sandbox), the service will not 
 return HS Codes. Instead, requests will remain in a pending status by default.
 Use the `hs_code_test` parameter in your Sandbox/integration environment to pass 
 an HS Code directly. In this case the product will not be reviewed by any operator,
 and a response will be sent back in a matter of minutes.

 There are two subscription options for the Item Classification API:
 - **Item Classification With Storage**: Your item metadata is automatically 
 stored as an [Avalara
 Item](https://developer.avalara.com/api-reference/avatax/rest/v2/models/ItemModel/) 
 object. This enables easy referencing of your items and metadata throughout
 Avalara using your own SKU.
 - **Item Classification Without Storage**: You have the flexibility to store 
 your classified items in a manner that best suits your needs. If you opt 
 for this, you can optionally set up a webhook to receive your classifications.

Avalara License

Avalara Item Classification API

Submit a product for HS classification for one or more countries of
destination. Each product (item) must be uniquely identified by itemCode
for a particular company. It is recommended to use your internal SKU
number as itemCode. Item classifications belong to the company you
designate.

## Dual-mode behavior

The same endpoint serves both auto-classification and manual
classification customers. The mode is chosen server-side based on
customer entitlement and the `async` query parameter:

- **Auto classification path** (synchronous prediction). Selected when:
  - The customer is entitled to **Auto HS**, **Auto HS Pro**, or **Auto HS ICP**, **and**
  - `async` is **not** `true` (i.e. omitted or `false`).

  The request is internally routed to the ML-based auto-classify flow
  (previously exposed as `/classifications/hscodes/auto`, now deprecated
  and removed from the public surface). The classification result is
  returned **synchronously** in the response body — there is no need to
  poll the GetHSClassification endpoint afterwards.

- **Manual classification path** (asynchronous parking-lot creation).
  Selected when:
  - The customer is **not** entitled to Auto HS / Auto HS Pro / Auto HS ICP, **or**
  - `async=true` is supplied (force manual flow even for entitled customers).

  The item is queued for manual classification. The response carries a
  `PENDING` status and the classification result can be retrieved later
  via `GET /classifications/hs/{hsClassificationId}`.

If the auto-classify path is selected but fails before invoking the
prediction service (e.g. authentication or payload conversion error),
the request automatically falls back to the manual classification path
so the call still succeeds.

## Request body

Both modes accept the **same** request body shape
(`HSClassificationModel` / `HSClassificationWithComplianceModel`).
Existing integrations do not need to change their payload to benefit
from auto-classification: simply enable Auto HS on the customer.

## Limits

- **Manual path:** maximum payload size of approximately 60KB. Exceeding
  this returns **413 Payload Too Large**. Split bulk-country requests if
  you hit the limit.
- **Auto path:** combined count (items × countries of destination) must
  not exceed the configured per-request limit (e.g. 10). Exceeding it
  returns **413 Payload Too Large**.


The ID of the company that owns this item. This is your integer company ID, not the string company code.

companyId

The unique identifier of the customer (for multi-tenant scenarios). When omitted, the customer is resolved from the authentication token.

customerId

When `true`, the response includes the Item Classification account id (`icAccountId`) for each classification entry. Defaults to `false` when not supplied.

returnIcAccountId

Forces the **manual classification path** (parking-lot creation) even when the customer is entitled to Auto HS / Auto HS Pro / Auto HS ICP. When omitted or `false`, entitled customers are auto-classified synchronously. When `true`, the item is always queued for manual classification and the response status will be `PENDING`.

async

Optional contextual metadata propagated to downstream services.

Context

The details for the item which requires HS classification.

Created. Returned for both modes:
- **Manual path:** the classification request was accepted and parked
  for manual classification; `status` is `PENDING`.
- **Auto path** (auto-HS-entitled customer, `async != true`): the
  classification was performed synchronously and the result is in
  the response body. `status` can be `CLASSIFIED_AUTOMATICALLY` (HS
  code predicted with sufficient confidence), `PENDING` (confidence
  threshold not met — item routed for manual classification), or a
  "Failed to Classify - Insufficient product information..." status
  when the model could not produce a prediction.
All country codes in the request were valid.


Multi-Status. Returned in two situations:
- **Manual path:** the request was partially successful — some
  country codes were valid and processed, while others were
  invalid (see `validCODs` / `invalidCODs`).
- **Auto path** (auto-HS-entitled customer, `async != true`,
  multiple items in the request): the body is a **JSON array** with
  one element per request item, in the **same order** as the input.
  Each element is either a full classification object or an error
  object describing the failure for that slot.


Bad request. Can be caused by a malformed JSON request or invalid parameter values.

Authentication required. Can be caused by missing or incorrect credentials.

Payload Too Large. Returned when either:
- **Manual path:** the request body exceeds the approximate 60KB
  size limit. Split into multiple smaller requests.
- **Auto path:** the combined count (items × countries of
  destination) exceeds the configured per-request limit.


Unsupported media type. The `Content-type` header has to be `application/json`.

Request cannot be processed due to validation errors.

Create an HS classification request (auto-classifies synchronously for Auto HS / Auto HS Pro / Auto HS ICP customers; otherwise queues for manual classification).

Returns the HS classification code. The status field reflects the actual state of the classification request.

The hsClassificationId used to identify a request was returned in the response of the CreateHSClassificationRequest method.

hsClassificationId

Successful get HS classification request response.

Authentication required. Can be caused by a missing or incorrect credentials.

The classification request id was not found in the system

Unsupported Media type. The `Content-type` header must be `application/json`.

Validates a list of HS codes for a given customer and company.
There is a limit to the number of HS codes that can be validated in a single request.
Requests exceeding this limit will be rejected with a 413 Payload Too Large error.

The customer must be enabled for HS code validation service.


HEADER_CONTEXT

The company is not provisioned for hs_code validation.

An invalid exception handler routine has been detected.

Service unavailable - HS Classification API not responding.

Verifies whether a provided HS code is appropriate for a given product using ML-based classification.

**Behavior:**
- If the HS code is verified as appropriate, returns `verified: true`
- If the HS code is NOT verified, automatically submits the product for classification and returns the classification response

**Requirements:**
- The customer must be enabled for HS code validation service
- HS code must be 6-12 digits, optionally followed by up to 2 letters (e.g., 7323997000, 7323997000AB)
- All standard classification fields are required (companyId, itemCode, description, itemGroup, countryOfDestination)

**Performance:**
- Typical response time: 1-2 seconds
- Timeout: 5 seconds
- Circuit breaker protection for service resilience


The unique identifier of the customer (for multi-tenant scenarios).

Validation error - missing required fields or invalid HS code format.

Service unavailable - ML classification service not responding or circuit breaker is open.

This is the endpoint that clients need to implement to receive webhook callbacks when classifications are completed.
Only clients who have specifically opted to receive webhook callbacks need to implement this endpoint.

**Authentication:**
The webhook callback supports two authentication methods:
- Basic Authentication: Avalara will send an Authorization header with "Basic {token}"
- OAuth: Avalara will send an Authorization header with "Bearer {token}"

**Response Requirements:**
- The endpoint should return HTTP 200 or 201 on success
- The recommended response format is: {"name":"API_RESPONSE","value":"SUCCESSFUL"}
- For errors, return HTTP 400 with: {"name":"API_RESPONSE","value":"ERROR"}

**Retry Behavior:**
If the webhook call fails due to server connectivity issues, the system will automatically retry the call.
Clients should ensure their webhook endpoint is reliable and responds quickly to avoid retry delays.


Webhook received and processed successfully (preferred response)

Tariff Code Classification

RestrictionsModel