Boxc CalculateDuty API

openapi: 3.2.0
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC Calculate Duty 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.

    '
servers:
- url: https://api.boxc.com/v1
tags:
- name: CalculateDuty
  x-displayName: Calculate Duty
  description: Calculate the landed cost of a shipment. This is a quick way to calculate the duties and taxes owed for a shipment without having to create one.
paths:
  /calculate-duty:
    post:
      tags:
      - CalculateDuty
      summary: POST /calculate-duty
      description: Calculate the landed cost of a shipment.
      operationId: calculateDuty
      security:
      - JWT:
        - calculate
      x-badges:
      - name: Beta
        position: after
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -X POST https://api.boxc.com/v1/calculate-duty \\\n    -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\n      \"calculate\": {\n        \"currency\": \"USD\",\n        \"shipping\": 0,\n        \"insurance\": 0,\n        \"origin\": {\n          \"country\": \"GB\"\n        },\n        \"destination\": {\n          \"province\": \"NY\",\n          \"country\": \"US\"\n        },\n        \"products\": [\n          {\n            \"coo\": \"GB\",\n            \"value\": 10,\n            \"currency\": \"GBP\",\n            \"quantity\": 20,\n            \"hs_code\": \"6109100040\",\n            \"description\": \"Cotton T-Shirt\"\n          }\n        ]\n      }\n  }'\n"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                calculate:
                  $ref: '#/components/schemas/CalculateDuty'
              required:
              - calculate
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  calculate:
                    $ref: '#/components/schemas/CalculateDuty'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                validation:
                  summary: Validation error
                  description: The request schema is invalid.
                  value:
                    code: 1000
                    message: 'calculate/origin/country: Required'
                    status: error
                    errors:
                    - calculate/origin/country is required
        '401':
          $ref: '#/components/schemas/Unauthorized'
        '402':
          $ref: '#/components/schemas/PaymentRequired'
        '403':
          $ref: '#/components/schemas/Forbidden'
        '429':
          $ref: '#/components/schemas/RateLimit'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
components:
  schemas:
    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.
    RateLimit:
      $ref: '#/components/schemas/rate-limit'
    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'
    CalculateDuty:
      $ref: '#/components/schemas/calculate-duty'
    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
    Forbidden:
      $ref: '#/components/schemas/forbidden'
    BadRequest:
      $ref: '#/components/schemas/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
    Unauthorized:
      $ref: '#/components/schemas/unauthorized'
    InternalServerError:
      $ref: '#/components/schemas/internal-server-error'
    PaymentRequired:
      $ref: '#/components/schemas/payment-required'
    calculate-duty:
      type: object
      title: Calculate Duty
      properties:
        currency:
          description: The ISO 4217 currency code. The result `tax` and `duty` values will be in this currency. The `insurance` and `shipping` values provided in the request must also be in this currency.
          type: string
          pattern: ^[A-Z]{3}$
          example: USD
        destination:
          type: object
          description: Details about the origin of the shipment.
          properties:
            city:
              type:
              - string
              - 'null'
              default: null
              maxLength: 40
              example: New York
            province:
              type:
              - string
              - 'null'
              default: null
              maxLength: 40
              example: NY
            postal_code:
              type:
              - string
              - 'null'
              maxLength: 40
              example: null
              default: null
            country:
              type: string
              pattern: ^[A-Z]{2}$
              example: US
          required:
          - country
        insurance:
          description: Amount paid for insuring the shipment.
          type: number
          minimum: 0
          default: 0
          example: 0
        origin:
          type: object
          description: Details about the destination of the shipment.
          properties:
            city:
              type:
              - string
              - 'null'
              default: null
              maxLength: 40
              example: null
            province:
              type:
              - string
              - 'null'
              default: null
              maxLength: 40
              example: null
            postal_code:
              type:
              - string
              - 'null'
              maxLength: 40
              example: null
              default: null
            country:
              type: string
              pattern: ^[A-Z]{2}$
              example: CN
          required:
          - country
        products:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: object
            properties:
              coo:
                description: The product's country of origin.
                type: string
                pattern: ^[A-Z]{2}$
                example: CN
              currency:
                description: The currency for the product value.
                type: string
                pattern: ^[A-Z]{3}$
                example: CNY
              description:
                description: A short description of the product.
                type: string
                minLength: 3
                maxLength: 64
                example: Cotton T-Shirt
              duty:
                description: The calculated duty for the product.
                type: number
                readOnly: true
                minimum: 0
                default: 0
                example: 23.52
              duty_rate:
                description: The calculated duty rate for the product.
                type: number
                readOnly: true
                minimum: 0
                default: 0
                example: 0.175
              hs_code:
                description: The HS Code for the product.
                type: string
                minLength: 6
                pattern: ^[0-9]{6,}$
                example: 6109100040
              quantity:
                description: The number of units of the product.
                type: integer
                minimum: 0
                example: 10
              tax:
                description: The calculated tax for the product.
                type: number
                readOnly: true
                minimum: 0
                default: 0
                example: 0
              tax_rate:
                description: The calculated tax rate for the product.
                type: number
                readOnly: true
                minimum: 0
                default: 0
                example: 0
              value:
                description: The per unit value of the product.
                type: number
                exclusiveMin: 0
                example: 10
            required:
            - coo
            - currency
            - description
            - hs_code
            - quantity
            - value
        shipping:
          description: Amount paid in shipping costs for the shipment.
          type: number
          minimum: 0
          default: 0
          example: 0
        total:
          description: null
          type: object
          readOnly: true
          properties:
            duty:
              description: The total duty for all products.
              type: number
              minimum: 0
              default: 0
              example: 23.52
            tax:
              description: The total tax for all products.
              type: number
              minimum: 0
              default: 0
              example: 0
      required:
      - currency
      - origin
      - destination
      - products
    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
  securitySchemes:
    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