Sphere Tax Calculations API

openapi: 3.0.1
info:
  title: Sphere Tax 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
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.
  /tax_api/exports:
    post:
      operationId: createTransactionExport
      tags:
        - Transactions Export
      summary: Create a transaction export job.
      description: >-
        Initiates an asynchronous export job over transaction data for
        reporting and reconciliation. Returns a job identifier used to poll for
        status and retrieve the resulting download.
      responses:
        '200':
          description: Export job created.
        '401':
          description: Missing or invalid API key.
  /tax_api/exports/{job_id}:
    get:
      operationId: getTransactionExport
      tags:
        - Transactions Export
      summary: Retrieve a transaction export job.
      description: >-
        Retrieves the status of an export job and, once complete, the download
        URL for the exported transaction data.
      parameters:
        - name: job_id
          in: path
          required: true
          description: The identifier of the export job to retrieve.
          schema:
            type: string
      responses:
        '200':
          description: Export job status and download details.
        '401':
          description: Missing or invalid API key.
        '404':
          description: Export job not found.
  /tax_api/exports/{job_id}/cancel:
    post:
      operationId: cancelTransactionExport
      tags:
        - Transactions Export
      summary: Cancel a transaction export job.
      description: Terminates a running or queued export job.
      parameters:
        - name: job_id
          in: path
          required: true
          description: The identifier of the export job to cancel.
          schema:
            type: string
      responses:
        '200':
          description: Export job cancelled.
        '401':
          description: Missing or invalid API key.
        '404':
          description: Export job not found.
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Sphere API key supplied in the X-API-KEY request header.
  schemas:
    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).
    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.
    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.
    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.
    TaxLine:
      type: object
      properties:
        id:
          type: string
          description: Line item or product identifier.
        tax_amounts:
          type: array
          items:
            $ref: '#/components/schemas/TaxAmount'
    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'
    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).
security:
  - api_key: []