Avalara Classification Requests API

openapi: 3.1.0
info:
  title: Avalara Item Classification Classification Requests 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: developer.relations@avalara.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://legal.avalara.com/#siteterms
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
security:
- bearerAuth: []
tags:
- name: Classification Requests
  description: Submit and manage product classification requests
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'
components:
  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:
    ClassificationRequestList:
      type: object
      properties:
        '@recordSetCount':
          type: integer
        value:
          type: array
          items:
            $ref: '#/components/schemas/ClassificationRequestSummary'
    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
    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
    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
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    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
    ClassificationRequestResponse:
      type: object
      properties:
        requestId:
          type: string
        status:
          type: string
          enum:
          - Pending
          - InProgress
        itemCount:
          type: integer
        submittedDate:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token
externalDocs:
  description: Item Classification API Documentation
  url: https://developer.avalara.com/api-reference/item-classification/v2/