swagger: '2.0'
info:
  x-logo:
    url: https://storage.googleapis.com/boxc_cdn/public/boxc-logo.png
    altText: BoxC
  title: BoxC CalculateDuty Invoices 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: Invoices
  x-displayName: Invoices
  description: Invoices and statements are generated weekly and include a summary of all transactions between the invoice's `start_date` and `end_date`. Users can export an itemized list of all transactions for a billing period in their account.
paths:
  /invoices:
    get:
      tags:
      - Invoices
      summary: GET /invoices
      description: Retrieves a paginated list of invoices.
      operationId: getInvoices
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - billing
      parameters:
      - in: query
        name: limit
        description: The number of results to return.
        required: false
        default: 50
        minimum: 50
        maximum: 100
        type: string
      - in: query
        name: order
        description: The sort order of the results.
        required: false
        default: desc
        type: string
        enum:
        - asc
        - desc
      - in: query
        name: page_token
        description: Used for selecting the page after the initial query.
        required: false
        type: string
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Accept: application/json\" \\\n  https://api.boxc.com/v1/invoices\\?limit=50\\&order=desc\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoices:
                    type: array
                    items:
                      $ref: '#/definitions/Invoice'
                  next_page:
                    type: string
                    description: Page token. Set by the system.
                    example: ZGF0ZV9lbmQ9MjAyMy0wNy0yOCZsaW1pdD01MCZvcmRlcj1kZXNjJnBhZ2U9MSZsYXN0X2lkPTE1Mzg0Nw
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/definitions/BadRequest'
              examples:
                invalidToken:
                  summary: Bad Request
                  description: Invalid page token
                  value:
                    code: 1025
                    message: Invalid page token
                    errors:
                    - Invalid page token
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '429':
          $ref: '#/definitions/RateLimit'
  /invoices/{id}:
    get:
      tags:
      - Invoices
      summary: GET /invoices/{id}
      description: Retrieves an invoice. Invoices before 2021-10-31 will not have a PDF.
      operationId: getInvoicesById
      consumes:
      - application/json
      produces:
      - application/json
      security:
      - JWT:
        - billing
      parameters:
      - name: Accept
        in: header
        required: false
        schema:
          type: string
          example: application/pdf
          enum:
          - application/json
          - application/pdf
        description: Optionally download the PDF.
      - in: query
        name: type
        description: Download the invoice and receipt documents.
        required: false
        deprecated: true
        type: string
        example: PDF
        enum:
        - PDF
      - name: id
        in: path
        description: The invoice ID
        required: true
        type: integer
      x-codeSamples:
      - lang: cURL
        label: cURL
        source: "curl -H \"Authorization: Bearer <YOUR TOKEN>\" \\\n  -H \"Accept: application/json\" \\\n  https://api.boxc.com/v1/invoices/{id}\n"
      responses:
        '200':
          description: Success OK. Returns PDF blob if `type=PDF` parameter is used.
          content:
            application/json:
              schema:
                type: object
                properties:
                  invoice:
                    $ref: '#/definitions/Invoice'
            application/pdf:
              type: string
        '401':
          $ref: '#/definitions/Unauthorized'
        '403':
          $ref: '#/definitions/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/definitions/NotFound'
              examples:
                notFound:
                  summary: Not Found
                  description: Invoice not found
                  value:
                    code: 1090
                    message: Invoice not found
                    errors:
                    - Invoice not found
        '429':
          $ref: '#/definitions/RateLimit'
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
  invoice:
    type: object
    properties:
      created:
        type: string
        description: The date and time the invoice was created in UTC.
        example: '2024-07-03 13:57:13'
        format: datetime
      currency:
        type: string
        description: The 3-letter currency code for the amount in this invoice.
        example: USD
      end_date:
        type: string
        description: The end date of the invoice in UTC.
        example: '2024-06-30'
      id:
        type: integer
        description: The unique ID of the invoice.
        example: 901934
      name:
        type: string
        description: The name of the invoice for grouping multiple invoices in different currencies together.
        example: 2024-W34
      start_date:
        type: string
        description: The start date of the invoice in UTC.
        example: '2024-06-01'
      total:
        type: decimal
        description: The total billed amount of the invoice.
        example: 2359.56
  NotFound:
    $ref: '#/definitions/not-found'
  Invoice:
    $ref: '#/definitions/invoice'
  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
  not-found:
    type: object
    summary: Not Found
    description: Object not found or not owned by the user
    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
  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