Quaderno Taxes API

openapi: 3.2.0
info:
  title: Quaderno Taxes API
  description: The Quaderno API is a REST API for tax compliance, invoicing, and sales tax / VAT automation.
  version: '1.0'
  contact:
    name: Quaderno
    url: https://developers.quaderno.io
  license:
    name: Proprietary
    url: https://quaderno.io/terms/
servers:
- url: https://{account}.quadernoapp.com/api
  description: Production (account-scoped)
  variables:
    account:
      default: ACCOUNT_NAME
      description: Your Quaderno account subdomain.
security:
- basicAuth: []
tags:
- name: Taxes
  description: Real-time tax rate calculation, jurisdictions, tax codes, and tax ID validation.
paths:
  /tax_rates/calculate.json:
    get:
      operationId: calculateTaxRate
      tags:
      - Taxes
      summary: Calculate a tax rate
      description: Calculates the applicable tax rate for a sale given the customer's country, region, postal code, tax ID, and optional product tax code. The response includes the rate, the tax name, and a status code explaining the reasoning (for example taxable, non_taxable, or not_registered).
      parameters:
      - name: country
        in: query
        required: true
        description: ISO 3166-1 alpha-2 country code of the customer.
        schema:
          type: string
      - name: postal_code
        in: query
        required: false
        description: Customer postal / ZIP code.
        schema:
          type: string
      - name: region
        in: query
        required: false
        description: State or region code (required for US sales tax).
        schema:
          type: string
      - name: tax_id
        in: query
        required: false
        description: Customer tax ID / VAT number, when applicable for reverse charge.
        schema:
          type: string
      - name: tax_code
        in: query
        required: false
        description: Product tax code identifying the taxability of the item.
        schema:
          type: string
      - name: amount
        in: query
        required: false
        description: Transaction amount used for threshold-sensitive determinations.
        schema:
          type: number
      responses:
        '200':
          description: The calculated tax rate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxCalculation'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tax_ids/validate.json:
    get:
      operationId: validateTaxId
      tags:
      - Taxes
      summary: Validate a tax ID
      description: Validates a customer tax ID / VAT number against the relevant government registry (for example VIES for EU VAT numbers).
      parameters:
      - name: country
        in: query
        required: true
        description: ISO 3166-1 alpha-2 country code.
        schema:
          type: string
      - name: tax_id
        in: query
        required: true
        description: The tax ID / VAT number to validate.
        schema:
          type: string
      responses:
        '200':
          description: Validation result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                  tax_id:
                    type: string
                  country:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tax_jurisdictions.json:
    get:
      operationId: listTaxJurisdictions
      tags:
      - Taxes
      summary: List tax jurisdictions
      description: Lists the tax jurisdictions the account is registered in, with the jurisdiction name, country, and region.
      parameters:
      - name: country
        in: query
        required: false
        description: Filter jurisdictions by country code.
        schema:
          type: string
      responses:
        '200':
          description: A list of tax jurisdictions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxJurisdiction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /tax_codes.json:
    get:
      operationId: listTaxCodes
      tags:
      - Taxes
      summary: List tax codes
      description: Lists the product tax codes available for classifying item taxability.
      responses:
        '200':
          description: A list of tax codes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxCode'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    TaxJurisdiction:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        country:
          type: string
        region:
          type: string
    TaxCalculation:
      type: object
      properties:
        country:
          type: string
        region:
          type: string
        county:
          type: string
        city:
          type: string
        name:
          type: string
          description: Human-readable tax name (for example VAT, GST, Sales Tax).
        rate:
          type: number
        tax_behavior:
          type: string
        notes:
          type: string
        status:
          type: string
          enum:
          - taxable
          - non_taxable
          - not_registered
          description: Reasoning for the calculated rate.
    TaxCode:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        errors:
          type: object
          additionalProperties: true
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication. Use your private API key as the username; the password can be any value. API keys are managed in the Quaderno account settings.