Sphere Tax Calculation API

openapi: 3.0.1
info:
  title: Sphere Tax Tax Calculation API
  description: Specification of the Sphere indirect tax compliance API. Sphere exposes a developer-first REST API for calculating sales tax, VAT, and GST inside billing and checkout flows, and for exporting transaction data. Requests are authenticated with an API key supplied in the X-API-KEY header. Only the endpoints publicly documented at docs.getsphere.com are modeled here; other Sphere capabilities (nexus monitoring, registration, filing and remittance, exemptions, webhooks) are delivered as platform features and do not have a documented public REST surface as of this writing.
  termsOfService: https://www.getsphere.com/
  contact:
    name: Sphere Support
    url: https://docs.getsphere.com/
  version: '1.0'
servers:
- url: https://server.getsphere.com
security:
- api_key: []
tags:
- name: Tax Calculation
paths:
  /tax_api/calculate_tax:
    post:
      operationId: calculateTax
      tags:
      - Tax Calculation
      summary: Calculate tax for a transaction.
      description: Calculates indirect tax (sales tax, VAT, GST) for one or more line items against a customer address and currency. Returns per-line tax amounts, taxable amounts, a tax rate breakdown (percentage, jurisdiction, country, state, tax type), and a unique calculation id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateTaxRequest'
            example:
              customer_id: cus_RQx5PQDFSMH6Ku
              customer_address:
                address1: Investors Boulevard
                city: Myrtle Beach
                state: SC
                postal_code: '29579'
                country: US
              line_items:
              - amount: 10000
                product_id: prod_RArEhwhXLfX5jF
                discount_amount: 0
                tax_inclusive: false
              currency: usd
      responses:
        '200':
          description: Tax calculated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateTaxResponse'
              example:
                message: Tax calculated successfully
                data:
                  lines:
                  - id: prod_RArEhwhXLfX5jF
                    tax_amounts:
                    - amount: 900
                      taxable_amount: 10000
                      tax_rate:
                        percentage: 9.0
                        inclusive: false
                        display_name: Sales Tax
                        jurisdiction: South Carolina
                        country: US
                        state: SC
                        tax_type: sales_tax
                  sphere_tax_calculation_id: cfd1e35a-ccb8-4bf1-86ed-49e332be220b
        '401':
          description: Missing or invalid API key.
components:
  schemas:
    LineItem:
      type: object
      required:
      - amount
      properties:
        id:
          type: string
          description: Optional line item identifier.
        amount:
          type: integer
          description: Line amount in the smallest currency unit (cents).
        product_id:
          type: string
          description: Product identifier used for tax categorization.
        discount_amount:
          type: integer
          description: Discount applied to the line, in cents.
        tax_inclusive:
          type: boolean
          description: Whether the amount is tax inclusive.
    TaxAmount:
      type: object
      properties:
        amount:
          type: integer
          description: Tax amount in cents.
        taxable_amount:
          type: integer
          description: Taxable amount in cents.
        tax_rate:
          $ref: '#/components/schemas/TaxRate'
    TaxLine:
      type: object
      properties:
        id:
          type: string
          description: Line item or product identifier.
        tax_amounts:
          type: array
          items:
            $ref: '#/components/schemas/TaxAmount'
    TaxRate:
      type: object
      properties:
        percentage:
          type: number
          description: Tax rate percentage.
        inclusive:
          type: boolean
        display_name:
          type: string
        jurisdiction:
          type: string
        country:
          type: string
        state:
          type: string
        tax_type:
          type: string
          description: Type of tax (e.g. sales_tax, vat, gst).
    CustomerAddress:
      type: object
      required:
      - country
      properties:
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
        postal_code:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
    CalculateTaxResponse:
      type: object
      properties:
        message:
          type: string
        data:
          type: object
          properties:
            lines:
              type: array
              items:
                $ref: '#/components/schemas/TaxLine'
            sphere_tax_calculation_id:
              type: string
              description: Unique identifier for this tax calculation.
    CalculateTaxRequest:
      type: object
      required:
      - customer_address
      - line_items
      - currency
      properties:
        customer_id:
          type: string
          description: Optional billing platform customer identifier.
        customer_address:
          $ref: '#/components/schemas/CustomerAddress'
        line_items:
          type: array
          description: One or more line items to calculate tax for.
          items:
            $ref: '#/components/schemas/LineItem'
        currency:
          type: string
          description: ISO 4217 currency code, lowercase only (e.g. usd).
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Sphere API key supplied in the X-API-KEY request header.