swagger: '2.0'
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty 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: 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
      consumes:
      - application/json
      produces:
      - application/json
      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: '#/definitions/CalculateDuty'
              required:
              - calculate
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  calculate:
                    $ref: '#/definitions/CalculateDuty'
        '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: 'calculate/origin/country: Required'
                    status: error
                    errors:
                    - calculate/origin/country is required
        '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:
  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'
  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
  CalculateDuty:
    $ref: '#/definitions/calculate-duty'
  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
  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.
  Unauthorized:
    $ref: '#/definitions/unauthorized'
  Forbidden:
    $ref: '#/definitions/forbidden'
  RateLimit:
    $ref: '#/definitions/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'
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