openapi: 3.1.0
info:
  title: Avalara Automated Tariff Code Classification API
  description: >-
    The Avalara HSCode and AvaTax Code Classification API classifies products
    into Harmonized System Codes (HS Codes) and Avalara Tax Codes. It provides
    tariff code predictions based on product information and destination country,
    with confidence levels for each classification result.
  version: '1.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
externalDocs:
  description: HS Code Classification API Documentation
  url: https://developer.avalara.com/api-reference/hscodeclassification/hscodeclassification/
servers:
- url: https://api.avalara.com/classification/v1
  description: HS Code Classification API Production
tags:
- name: Classification
  description: Classify products into HS Codes and tax codes
security:
- bearerAuth: []
paths:
  /classify:
    post:
      operationId: classifyProduct
      summary: Avalara Classify a Product
      description: >-
        Classifies a product into HS Code and Avalara Tax Code based on
        the provided product description, attributes, and destination country.
        Returns predictions with confidence scores.
      tags:
      - Classification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassifyRequest'
      responses:
        '200':
          description: Classification results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClassifyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /classify/batch:
    post:
      operationId: classifyBatch
      summary: Avalara Classify a Batch of Products
      description: Classifies multiple products in a single request.
      tags:
      - Classification
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassifyRequest'
                destinationCountry:
                  type: string
      responses:
        '200':
          description: Batch classification results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClassifyResponse'
  /hscodes/{hsCode}:
    get:
      operationId: getHSCode
      summary: Avalara Look Up an HS Code
      description: Retrieves details for a specific HS Code.
      tags:
      - Classification
      parameters:
      - name: hsCode
        in: path
        required: true
        schema:
          type: string
      - name: country
        in: query
        schema:
          type: string
        description: Country for country-specific tariff details
      responses:
        '200':
          description: HS Code details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HSCodeInfo'
  /hscodes/{hsCode}/hierarchy:
    get:
      operationId: getHSCodeHierarchy
      summary: Avalara Get HS Code Hierarchy
      description: >-
        Returns the full hierarchy for an HS Code from chapter through
        heading, subheading, and national tariff line.
      tags:
      - Classification
      parameters:
      - name: hsCode
        in: path
        required: true
        schema:
          type: string
      - name: country
        in: query
        schema:
          type: string
      responses:
        '200':
          description: HS Code hierarchy
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HSCodeInfo'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ClassifyRequest:
      type: object
      required:
      - description
      - destinationCountry
      properties:
        description:
          type: string
          description: Product description for classification
        destinationCountry:
          type: string
          description: ISO 3166-1 alpha-2 destination country
        originCountry:
          type: string
          description: ISO 3166-1 alpha-2 origin country
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Additional product attributes
        itemCode:
          type: string
          description: Product identifier
    ClassifyResponse:
      type: object
      properties:
        itemCode:
          type: string
        description:
          type: string
        predictions:
          type: array
          items:
            $ref: '#/components/schemas/ClassificationPrediction'
        avataxCode:
          type: string
          description: Recommended Avalara tax code
    ClassificationPrediction:
      type: object
      properties:
        hsCode:
          type: string
          description: Predicted HS Code
        description:
          type: string
          description: HS Code description
        confidence:
          type: number
          format: double
          description: Confidence score (0-1)
        parentCode:
          type: string
    HSCodeInfo:
      type: object
      properties:
        hsCode:
          type: string
        description:
          type: string
        level:
          type: string
          enum:
          - Section
          - Chapter
          - Heading
          - Subheading
          - TariffLine
        parentCode:
          type: string
        dutyRate:
          type: string
        unitOfMeasure:
          type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string