Create a request to HS classify an item for a single country 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.

There is a maximum payload size limit of approximately 60KB for this endpoint. 
If your request exceeds this limit, you will receive a 413 Payload Too Large response.
For bulk country classification, you can split your request into multiple requests 
with fewer country codes if you encounter size limits.


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

companyId

The details for the item which requires HS classification.

Successfully received the HS classification request. All country codes were valid.

Multi-Status. The request was partially successful. Some country codes were valid and processed, while others were invalid.

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

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

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

Request cannot be processed due to validation errors.

Creates a request to HS classify an item for a single country of destination.

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.


customerId

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

Context

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)

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, manufacturer_name, 
country_of_manufacture, country_of_export.

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.

HsValidCodeRequest