swagger: '2.0'
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Classify API
  version: '1.123'
  description: 'A simple but powerful logistics API that drives international ecommerce by utilizing a single integration with access to dozens of carriers and global markets. BoxC can complete every leg or only select steps of a shipment''s journey on your behalf with our routing engine.

    '
schemes:
- https
tags:
- name: Classify
  x-displayName: Classify
  description: The Classify resource permits a user to retrieve the <em>most likely</em> HS code and description for one or more products. Each successful request costs $0.05 (USD) regardless of the number of products.
paths:
  /classify:
    post:
      tags:
      - Classify
      summary: POST /classify
      description: Get HS codes and descriptions for products. Accurate HS codes are required for customs clearance.
      operationId: addClassify
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - classify
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/classify \\\n    -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"classify\": {\n        \"destination_country\": \"US\",\n        \"origin_country\": \"CN\",\n        \"products\": [\n          {\n            \"hs_code\": \"610610\",\n            \"description\": \"Sports Bra\"\n          }\n        ]\n      }\n    }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                classify:
                  $ref: '#/definitions/Classify'
              required:
              - classify
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  classify:
                    $ref: '#/definitions/Classify'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/definitions/BadRequest'
              examples:
                validation:
                  summary: Validation error
                  description: The request schema is invalid.
                  value:
                    code: 1000
                    message: 'classify/origin_country: Required'
                    status: error
                    errors:
                    - origin_country is required
                hsCode:
                  summary: Missing Requirements
                  description: An HS Code and description are required for all products.
                  value:
                    code: 1215
                    message: Shipment requires an HS Code and description for all line items
                    errors:
                    - Shipment requires an HS Code and description for all line items
        '401':
          $ref: '#/definitions/Unauthorized'
        '402':
          $ref: '#/definitions/PaymentRequired'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/definitions/InternalServerError'
              examples:
                internalServerError:
                  summary: Internal Server Error
                  description: Service Unavailable
                  value:
                    code: 1010
                    message: Service Unavailable
                    errors:
                    - Service Unavailable
                chargingError:
                  summary: Internal Server Error - Charging Account
                  description: Unable to deduct amount from balance
                  value:
                    code: 1010
                    message: Unable to deduct amount from balance
                    errors:
                    - Unable to deduct amount from balance
definitions:
  forbidden:
    description: Forbidden
    content:
      application/json:
        schema:
          type: object
          summary: Forbidden
          description: Error relating to insufficient permissions for a resource
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          revoked:
            summary: Forbidden Authorization Revoked
            description: 'Forbidden: Authorization revoked'
            value:
              code: 1008
              message: 'Forbidden: Authorization revoked'
              errors:
              - 'Forbidden: Authorization revoked'
          scope:
            summary: Forbidden Scope
            description: 'Forbidden: Missing required scope'
            value:
              code: 1009
              message: 'Forbidden: Missing required scope'
              errors:
              - 'Forbidden: Missing required scope'
  bad-request:
    type: object
    summary: Bad Request
    description: Validation error with the request
    properties:
      code:
        description: Error code. Refer to the list of [Errors](/#tag/Errors).
        type: integer
      message:
        description: Error message explaining the code.
        type: string
      status:
        type: string
        enum:
        - error
        example: error
      errors:
        description: Lists validation errors with the schema or the resource being operated on.
        type: array
        minItems: 1
        maxItems: 5
        items:
          type: string
  PaymentRequired:
    $ref: '#/definitions/payment-required'
  InternalServerError:
    $ref: '#/definitions/internal-server-error'
  payment-required:
    description: Payment Required
    content:
      application/json:
        schema:
          type: object
          summary: Payment Required
          description: There are insufficient funds available for this resource
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Duplicate of the error message
              type: array
              items:
                type: string
        examples:
          paymentRequired:
            summary: Payment Required
            description: Insufficient funds
            value:
              code: 1080
              message: Insufficient funds
              errors:
              - Insufficient funds
  classify:
    x-extendedDiscriminator: summary
    type: object
    properties:
      summary: null
      destination_country:
        description: The destination country code.
        type: string
        pattern:
        - A-Z
        example: US
        minLength: 2
        maxLength: 2
      origin_country:
        description: The origin country code.
        type: string
        pattern:
        - A-Z
        example: CN
        minLength: 2
        maxLength: 2
      products:
        type: array
        description: List of products to classify.
        minimum: 1
        maximum: 20
        items:
          type: object
          properties:
            hs_code:
              type: string
              description: The HS code for the product if known.
              pattern:
              - 0-9
              example: '610610'
              minLength: 6
              maxLength: 10
            description:
              type: string
              description: A description of the product.
              example: Sports Bra
              minLength: 3
              maxLength: 128
            result:
              readOnly: true
              type: object
              properties:
                import_hs_code:
                  type: string
                  description: The <em>most likely</em> 10-digit HS code of the product for the destination country.
                  example: '6212109020'
                  minLength: 10
                  maxLength: 10
                export_hs_code:
                  type: string
                  description: The <em>most likely</em> 10-digit HS code of the product for the origin country.
                  example: '6115950000'
                  minLength: 10
                  maxLength: 10
                description:
                  type: string
                  description: The <em>most likely</em> description of the product.
                  example: Socks
          required:
          - description
    required:
    - destination_country
    - origin_country
    - products
  BadRequest:
    $ref: '#/definitions/bad-request'
  unauthorized:
    description: Unauthorized
    content:
      application/json:
        schema:
          type: object
          summary: Unauthorized
          description: Lack of valid authentication credentials for the resource
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          accessToken:
            summary: Invalid access token
            description: Invalid access token
            value:
              code: 1005
              message: Invalid access token
              errors:
              - Invalid access token
  internal-server-error:
    type: object
    summary: Internal Server Error
    description: Processing Error
    properties:
      code:
        description: Error code. Refer to the list of [Errors](/#tag/Errors).
        type: integer
      message:
        description: Error message explaining the code.
        type: string
      status:
        type: string
        enum:
        - error
        example: error
      errors:
        description: Displays processing error.
        type: array
        minItems: 1
        maxItems: 1
        items:
          type: string
  rate-limit:
    description: Too Many Requests
    content:
      application/json:
        schema:
          type: object
          summary: Too Many Requests
          description: Error for too many requests in a given time frame. See [Rate Limits](/#tag/RateLimit) for more information.
          properties:
            code:
              description: Error code. Refer to the list of [Errors](/#tag/Errors).
              type: integer
            message:
              description: Error message explaining the code.
              type: string
            status:
              type: string
              enum:
              - error
              example: error
            errors:
              description: Displays processing error.
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
        examples:
          rateLimit:
            summary: Too Many Requests
            description: Too many requests. Please wait before trying again.
            value:
              code: 1015
              message: Too many requests. Please wait before trying again.
              errors:
              - Too many requests. Please wait before trying again.
  Forbidden:
    $ref: '#/definitions/forbidden'
  Unauthorized:
    $ref: '#/definitions/unauthorized'
  RateLimit:
    $ref: '#/definitions/rate-limit'
  Classify:
    $ref: '#/definitions/classify'
securityDefinitions:
  JWT:
    type: http
    scheme: bearer
    bearerScheme: JWT
    in: header
    description: All operations require a JSON Web Token after completing an [OAuth2 flow](#tag/Authentication).
  PrivilegedClient:
    type: http
    scheme: bearer
    bearerScheme: JWT
    description: Some clients require special privileges to use operations. No additional scope is needed.
x-servers:
- url: https://api.boxc.com/v1
x-tagGroups:
- name: Overview
  tags:
  - Introduction
  - Authentication
  - RateLimit
  - Paginate
  - Changelog
- name: Operations
  tags:
  - CalculateDuty
  - Classify
  - Invoices
  - Users
  - ValidateAddress
  - Webhooks
- name: Shipping
  tags:
  - Credentials
  - CustomsProducts
  - EntryPoints
  - Estimate
  - Labels
  - Manifests
  - Overpacks
  - Shipments
  - Track
- name: Fulfillment
  tags:
  - Inbound
  - Orders
  - Products
  - Shops
  - Warehouses
- name: Returns
  tags:
  - Reshipments
  - Returns
- name: Data
  tags:
  - CarrierCredentials
  - DangerousGoods
  - Errors
  - Languages
  - CarrierParameters
  - ReturnsProcess
  - TrackingEvents