openapi: 3.0.3
info:
  title: TaxJar Sales Tax Categories Summary Rates API
  description: REST API for real-time sales tax calculation, rooftop-level rate lookups, tax category listing, transaction management (orders and refunds), customer exemption management, nexus region tracking, address validation, and VAT validation. Supports token-based authentication via Authorization header. TaxJar is a Stripe company providing sub-20ms response times and 99.999% historical uptime.
  version: '2.0'
  contact:
    name: TaxJar Developer Support
    url: https://support.taxjar.com/category/233-taxjar-api
  termsOfService: https://www.taxjar.com/terms/
  x-api-id: taxjar-sales-tax
servers:
- url: https://api.taxjar.com/v2
  description: Production
- url: https://api.sandbox.taxjar.com/v2
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Summary Rates
  description: Summarized sales tax rates by region
paths:
  /summary_rates:
    get:
      operationId: listSummaryRates
      summary: Summarize tax rates for all regions
      description: Returns a summarized list of expected sales tax rates for a given region. This is useful for showing customers an estimated tax rate before checkout.
      tags:
      - Summary Rates
      responses:
        '200':
          description: Summary rates by region
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary_rates:
                    type: array
                    items:
                      $ref: '#/components/schemas/SummaryRate'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    SummaryRate:
      type: object
      properties:
        country_code:
          type: string
          description: Two-letter ISO country code
          example: US
        country:
          type: string
          description: Country name
          example: United States
        region_code:
          type: string
          description: Two-letter state/region code
          example: CA
        region:
          type: string
          description: State/region name
          example: California
        minimum_rate:
          type: object
          properties:
            label:
              type: string
              example: State Tax
            rate:
              type: number
              format: float
              example: 0.065
        average_rate:
          type: object
          properties:
            label:
              type: string
              example: Tax
            rate:
              type: number
              format: float
              example: 0.0827
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error type
        detail:
          type: string
          description: Human-readable error detail
        status:
          type: integer
          description: HTTP status code
  responses:
    Unauthorized:
      description: Unauthorized - invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use your TaxJar API token. Format: "Bearer [token]" or "Token token=[token]"'