The Avalara Item Classification API allows users subscribed to the Item Classification service to submit products for classification and retrieve the corresponding HS Codes, with support for storage and non-storage subscription models.
openapi: 3.1.0
info:
title: Avalara Item Classification API
description: >-
The Avalara Item Classification API allows businesses subscribed to the
Item Classification service to submit products for automated classification,
retrieve corresponding HS Codes, and manage classification requests. It
supports both storage and non-storage subscription models for product
classification across international trade jurisdictions.
version: '2.0'
contact:
name: Avalara Developer Relations
url: https://developer.avalara.com/
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
termsOfService: https://legal.avalara.com/#siteterms
externalDocs:
description: Item Classification API Documentation
url: https://developer.avalara.com/api-reference/item-classification/v2/
servers:
- url: https://api.avalara.com/classification/v2
description: Item Classification API Production
- url: https://api.sbx.avalara.com/classification/v2
description: Item Classification API Sandbox
tags:
- name: Classification Requests
description: Submit and manage product classification requests
- name: HS Codes
description: Retrieve HS Code classification results
security:
- bearerAuth: []
paths:
/classification-requests:
post:
operationId: createClassificationRequest
summary: Avalara Submit Products for Classification
description: >-
Submits one or more products for HS Code classification. Products
are classified based on their descriptions and attributes for the
specified destination country.
tags:
- Classification Requests
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationRequest'
responses:
'202':
description: Classification request accepted
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationRequestResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listClassificationRequests
summary: Avalara List Classification Requests
description: Retrieves a list of submitted classification requests and their statuses.
tags:
- Classification Requests
parameters:
- name: status
in: query
schema:
type: string
enum:
- Pending
- InProgress
- Completed
- Failed
- name: $top
in: query
schema:
type: integer
- name: $skip
in: query
schema:
type: integer
responses:
'200':
description: List of classification requests
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationRequestList'
/classification-requests/{requestId}:
get:
operationId: getClassificationRequest
summary: Avalara Get Classification Request Status
description: Retrieves the status and results of a classification request.
tags:
- Classification Requests
parameters:
- name: requestId
in: path
required: true
schema:
type: string
responses:
'200':
description: Classification request details
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationRequestDetail'
'404':
$ref: '#/components/responses/NotFound'
/classification-requests/{requestId}/results:
get:
operationId: getClassificationResults
summary: Avalara Get Classification Results
description: >-
Retrieves the HS Code classification results for a completed
classification request.
tags:
- HS Codes
parameters:
- name: requestId
in: path
required: true
schema:
type: string
responses:
'200':
description: Classification results
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationResultList'
/hs-codes/{hsCode}:
get:
operationId: getHSCodeDetails
summary: Avalara Get HS Code Details
description: Retrieves detailed information for a specific HS Code.
tags:
- HS Codes
parameters:
- name: hsCode
in: path
required: true
schema:
type: string
description: The HS Code to look up
- name: country
in: query
schema:
type: string
description: ISO 3166-1 alpha-2 country code for country-specific details
responses:
'200':
description: HS Code details
content:
application/json:
schema:
$ref: '#/components/schemas/HSCodeDetail'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: OAuth 2.0 bearer token
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ClassificationRequest:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/ClassificationItem'
destinationCountry:
type: string
description: ISO 3166-1 alpha-2 destination country code
ClassificationItem:
type: object
required:
- description
properties:
itemCode:
type: string
description: Unique item identifier
description:
type: string
description: Product description for classification
summary:
type: string
description: Short product summary
attributes:
type: object
additionalProperties:
type: string
description: Additional product attributes for classification
ClassificationRequestResponse:
type: object
properties:
requestId:
type: string
status:
type: string
enum:
- Pending
- InProgress
itemCount:
type: integer
submittedDate:
type: string
format: date-time
ClassificationRequestList:
type: object
properties:
'@recordSetCount':
type: integer
value:
type: array
items:
$ref: '#/components/schemas/ClassificationRequestSummary'
ClassificationRequestSummary:
type: object
properties:
requestId:
type: string
status:
type: string
itemCount:
type: integer
submittedDate:
type: string
format: date-time
completedDate:
type: string
format: date-time
ClassificationRequestDetail:
type: object
properties:
requestId:
type: string
status:
type: string
enum:
- Pending
- InProgress
- Completed
- Failed
itemCount:
type: integer
classifiedCount:
type: integer
submittedDate:
type: string
format: date-time
completedDate:
type: string
format: date-time
ClassificationResultList:
type: object
properties:
value:
type: array
items:
$ref: '#/components/schemas/ClassificationResult'
ClassificationResult:
type: object
properties:
itemCode:
type: string
description:
type: string
hsCode:
type: string
description: Classified HS Code
hsCodeDescription:
type: string
confidence:
type: number
format: double
description: Classification confidence score (0-1)
country:
type: string
HSCodeDetail:
type: object
properties:
hsCode:
type: string
description:
type: string
chapter:
type: string
section:
type: string
parentCode:
type: string
dutyRate:
type: string
unitOfMeasure:
type: string
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string