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.

Core capabilities

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.

Getting started

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

How it integrates

What Self-Serve Tariff Code Classification solves

When to use Self-Serve Tariff Code Classification

Self-Serve Tariff Code Classification

Get Started

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

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.

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.

Tariff Code Classification

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

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

ClassyVue integration guide

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

Standard error response payload returned by the API when a request fails. Provides a short error title, the HTTP status code, and a human-readable detail message.

Invalid Request

Human-readable explanation of the specific error condition. Suitable for surfacing to end users or logging.

HTTP status code returned with the error response.

Identifier of the interaction (question) being answered. This corresponds to the 'id' field of an interaction returned in the previous classification response.

Discriminator identifying this as a request to continue an existing classification. Must be 'CONTINUE'.

Identifier of the classification transaction returned by a previous classification response. Note: this request field is named 'txid' (lowercase 'i') for backwards compatibility, while the corresponding response field is 'txId'. Both refer to the same value.

Answers selected for the current interaction. Each entry in the list is a map with the fixed keys 'first' and 'second'. The semantics depend on the interaction's 'type' field returned in the previous response:
- SELECTION (single answer): one entry where 'first' is the selected option id and 'second' is the option's user-visible label.
- VALUED (multiple ingredients, mixed content): one entry per ingredient where 'first' is the option id and 'second' is the ingredient's percentage as a numeric string. The percentages across all entries must sum to 100.

Request body used to continue an in-progress self-serve tariff classification by answering the questions returned in a prior response. The 'state' field acts as the discriminator and must be 'CONTINUE'. All fields are required.

An option/attribute returned for a classification interaction. Each attribute represents a candidate answer (e.g. a material, condition, or ingredient) the caller may select when continuing the classification.

antique

Definition or descriptive gloss of the option when available. May be empty.

Frequency count from the underlying ontology, indicating how often this option occurs for products of this type.

Identifier of this option (UUID). Echo this value as the 'first' field of a values entry in a continue request to select this option.

Optional generalization category ("kind of") for the option, such as a material family or product class. May be empty.

Display name of the option in the response language.

Numeric form of 'value', provided as a convenience for VALUED (mixed-content) interactions so clients do not need to parse the string. When populated, equals Double.valueOf(value). Null for non-VALUED interactions, and also null when 'value' is non-numeric.

Concept hierarchy path of the option, with components separated by '//'. Populated for ITEM-type interactions; null for other interaction types.

Selection or weighting state of the option. For VALUED interactions, this is the percentage assigned to the option as a numeric string ("0" when no percentage was set). For SELECTION and other interaction types, this is the literal string of the option, e.g. "knitted"

A classification interaction returned in a classification response. Interactions group together a question prompt, the available options (attrs), and metadata about how the question was answered or inferred.

composition

True when the currently-selected option is the "other" / fallback option.

Available options (candidate answers) for this interaction. Each entry describes one option, including its identifier, display name, and current selection state.

True when this interaction includes an explicit "other" / fallback option.

Single HS heading or subheading(4 or 6-digit code) associated with this interaction, if any. Empty string when the interaction is not tied to a specific heading.

Comma-separated list of HS headings or subheadings that remain in scope for this interaction's solution space. Sorted ascending.

Identifier of this interaction. Echo this value as 'interactionid' in a continue request to answer this specific question.

Source of the answer for this interaction.

Localized display label of the question's category. Always equal to 'name' (both fields carry the same value, retained for backward compatibility).

Response language as an ISO 639-1 code. Defaults to 'EN'.

Localized display label of the question's category. Always equal to 'label' (both fields carry the same value, retained for backward compatibility). May include compositional context, for example "whole of the propeller" or "power source location of the power source". For TARIFF_SCHEDULE interactions this is the literal string "underspecified".

True when the answer chosen for this interaction conflicts with a profile rule that would otherwise apply.

Definition of the selected option, populated only for SELECTION interactions when the selected option has a definition. Empty otherwise.

Display string of the currently-selected answer(s). For SELECTION interactions, this is the selected option's name. For VALUED interactions, this is a semicolon-separated list of "<percentage>% <name>" entries. Lazily computed from 'attrs' when not explicitly set.

True when the question carries a known semantic ambiguity (for example, the product description matches multiple distinct concepts).

Wire-level interaction type. Determines how the caller should answer the question and how 'attrs[].value' / 'attrs[].number' should be interpreted.

Display string for unselected options, with a language-specific negative prefix (for example, "not cotton; not wool"). Lazily computed from 'attrs' when not explicitly set; null until first computed.

Response payload for a self-serve classification request. Carries the transaction identifier, the current state of the classification (selected item, candidate HS code, pending and resolved interactions), supporting metadata, and any error indicators.

Interactions whose answer was assumed by the engine via exception rules rather than asked of the user.

Authoritative sources (for example, CROSS rulings) that support the current classification.

Definition of the selected item from the underlying ontology. Empty when no definition is available.

The currently pending item-selection interaction, when the engine is asking the caller to confirm which item the product description refers to. Null when no item-selection question is pending.

Display name of the item currently selected by the engine. Set to "UNKNOWN_ITEM" when no item could be identified.

Concept hierarchy paths ("//"-separated) of candidate items inferred from the product description. Useful for understanding how the engine interpreted the input.

The currently pending question that the caller is expected to answer in a continue request. Null when the classification has reached a final HS code or has errored out.

Selected Item Path: concept hierarchy path ("//"-separated, root-to-leaf) of the selected item.

Build timestamp of the underlying classification graph used for this response. Returned as a free-form string wrapped in literal single quotes.

HS schedule version used for this classification. Equal to 'schedule'.

Time spent processing the request, in milliseconds.

Human-readable detail of the error, populated when one of the *Error flags is set.

Classified HS code (typically 6 or 8 digits; 4-digit headings are zero-padded to 6 digits when the schedule stops at HS6). Empty until enough information has been gathered to reach a classification.

True when the engine raised an ItemOutOfScopeException, indicating the selected item falls outside the supported tariff scope (HTTP-level status 900). Null otherwise.

Interactions whose answer is currently known (resolved), either by a profile rule or because the user has already answered them.

Response language as an ISO 639-1 code, echoing the language used to build the response.

True when the engine raised a MixedContentException, indicating the product description requires a mixed-content (VALUED) breakdown that has not been provided (HTTP-level status 905). Null otherwise.

True when the engine raised a MultipleItemException, indicating the product description references more than one distinct item (HTTP-level status 902), like sets and kits. Null otherwise.

All past interactions in the order they were asked or resolved during this classification session.

HS headings that remain in scope as potential matches given the information gathered so far.

Product description that was submitted in the originating classification request, echoed back here for reference.

Comma-separated list of GRI rules and HS legal notes that justify the current classification.

HS schedule version used for this classification. Equal to 'dataVersion'.

True when the engine encountered an unhandled or unrecoverable error (HTTP-level status 901). Null when no system error occurred.

Identifier of the classification transaction. Echo this value as 'txid' (lowercase 'i') in a continue request. Note: this response field is named 'txId' (camelCase) while the corresponding request field is 'txid' (lowercase 'i'); both refer to the same value, the casing difference is retained for backward compatibility.

Destination country code in ISO 3166-1 alpha-2 format. When provided, the customer must be subscribed to this destination.

Response language as an ISO 639-1 code. Defaults to 'EN' when omitted.

Country of origin in ISO 3166-1 alpha-2 format.

Free-form product description to classify. Required.

Discriminator identifying this as a request to start a new classification. Must be 'START'.

Request body used to start a new self-serve tariff classification. The 'state' field acts as the discriminator and must be 'START'. 'proddesc' is required; 'destination', 'origin', and 'lang' are optional.

A destination country supported by the customer's profile, including the country code, display name, and the Harmonized System (HS) version that applies for that destination.

United States

Date from which the current HS version became effective for this destination, in ISO 8601 (YYYY-MM-DD) format.

Harmonized System (HS) version that applies to this destination.

Destination country code in ISO 3166-1 alpha-2 format.

Customer profile information, including the AvaTax account identifier, the customer name, the list of subscribed services, the supported and subscribed destination countries, and the customer's destination subscription limit.

AvaTax account identifier for the customer.

Display name of the customer or organization.

Destination countries supported by the customer's profile, with the HS version and effective date that applies to each.

Maximum number of destinations the customer is allowed to subscribe to.

Destination country codes (ISO 3166-1 alpha-2, uppercase) the customer is currently subscribed to.

Services the customer is subscribed to. Known values include XBOSelfServe (Self-Serve Tariff Classification), XBOTariffContent (Tariff Content), and XBOTradecompliance (Trade Compliance).

### Access to the Production API
To interact with this API, you need to acquire a bearer token.
To acquire a bearer token:
1. [Create a License Key](https://knowledge.avalara.com/bundle/bhk1662649440973_bhk1662649440973/page/Get_your_license_key.html).
2. Call Avalara Identity to get an access token:
    ```bash
        curl -X POST https://identity.avalara.com/connect/token
             -H "Content-Type: application/x-www-form-urlencoded"
             -d "grant_type=client_credentials&client_id=<avatax_account_id>&client_secret=<license key>&scope=avatax_api"
    ```
    Sample response (json)
    ```json
        {
            "access_token": "<jwt_access_token>",
            "expires_in": 3600,
            "token_type": "Bearer",
            "scope": "avatax_api"
        }
    ```
3. The `access_token` can be used to interact with the API.
4. The `access_token` is valid for 1 hour, after which you will need to request a fresh token.

### Access to the Sandbox API
To interact with the Sandbox API, you can request for a bearer token from your Avalara integration specialist.
You can use the bearer token issued for a fixed number of requests against the sandbox API.


Avalara Cross Border Classification

Gets a PDF certificate based on destination country, origin country, transaction id, and HS code. Returns the certificate as a PDF file attachment ready for download or viewing.

The code for destination country in ISO 3166-1 alpha-2 format.

destination

The code for origin country in ISO 3166-1 alpha-2 format.

origin

txid

The HS (Harmonized System) code for the product.

hscode

The username associated with the certificate.

username

fullname

avalara-version

Authentication failed due to invalid or missing authentication token.

Customer is not authorized to access this resource.

Classifies products based on the provided request data. Supports start and continue actions for interactive classification.

Classification request with state field that must be either 'START' or 'CONTINUE'.

Classification request body. The 'state' field in the request must be either 'START' or 'CONTINUE' and determines which type of request is processed.

Gets notes and documentation for a specific HS code based on destination country and language. Supports both import and export notes with JSON or HTML format options.

language

Indicates whether to retrieve import notes. Set to true to retrieve import notes, or false to retrieve export notes.

import

The format for the response. Allowed values: json, html.

format

Returns notes and documentation for the requested HS code, destination, and language.

Notes not found for the specified HS code, destination, and language.

Gets the user profile based on the authentication token. Returns profile details including ID, customer information, and subscribed destinations.

AvaTax account identifier of the profile to retrieve. Must match the 'avatax_account_id' claim of the bearer token; the request is rejected with HTTP 401 otherwise.

avalaraId

Returns the user profile for the authenticated request.

Self-Serve Tariff Code Classification

ClassificationStartRequest