Complete guide to managing tax configurations, calculations, and compliance via the API

Tax API

The Tax API provides comprehensive tax management capabilities for your subscription business. It handles tax configuration, nexus settings, rate definitions, registrations, and automated tax calculations to ensure compliance across different jurisdictions.

Overview

The Tax API enables you to:

Configure Tax Settings: Set up automatic tax calculation and default tax rates
Manage Nexus: Configure US state nexus settings for sales tax compliance
Define Tax Rates: Create custom tax rate definitions for different products or services
Tax Registrations: Manage tax registrations across different jurisdictions
Preview Calculations: Test tax calculations before processing actual transactions

Key Concepts

Tax Configuration

Global tax settings for your merchant account, including whether to enable automatic tax calculation and default tax rates.

Nexus Configuration

US state-specific settings that determine where you have tax obligations. Each state where you have nexus requires specific configuration.

Tax Rate Definitions

Custom tax rates that can be applied to specific products, services, or customer segments.

Tax Registrations

Records of your tax registrations with various tax authorities.

Authentication

All API requests require authentication via merchant credentials.

Endpoints

Get Tax Configuration

Get the current tax configuration for the authenticated merchant.

GET /api/tax/config

Response

{
  "autoTaxCalculation": true,
  "defaultTaxRate": "0.0875"
}

Response Fields

Field	Type	Description
`autoTaxCalculation`	boolean	Whether automatic tax calculation is enabled
`defaultTaxRate`	string	Default tax rate as decimal (e.g., "0.0875" for 8.75%)

Update Tax Configuration

Update the tax configuration settings for your merchant account.

POST /api/tax/config/update

Request Body

{
  "autoTaxCalculation": true,
  "defaultTaxRate": "0.0875"
}

Request Fields

Field	Type	Required	Description
`autoTaxCalculation`	boolean		Enable/disable automatic tax calculation
`defaultTaxRate`	string		Default tax rate as decimal (0.0 to 1.0) or null

Response

{
  "id": "config_123",
  "merchantId": "merchant_123",
  "autoTaxCalculation": true,
  "defaultTaxRate": "0.0875",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get US Nexus Configurations

Get all US nexus configurations for the authenticated merchant.

GET /api/tax/nexus

Response

[
  {
    "id": "nexus_123",
    "merchantId": "merchant_123",
    "state": "CA",
    "isActive": true,
    "effectiveDate": "2024-01-01T00:00:00Z",
    "registrationNumber": "SR-123456789",
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Update US Nexus Configuration

Update nexus configuration for a specific US state.

POST /api/tax/nexus/{state}/update

Parameters

Parameter	Type	Description
`state`	string	Two-letter US state code

Request Body

{
  "isActive": true,
  "effectiveDate": "2024-01-01T00:00:00Z",
  "registrationNumber": "SR-123456789"
}

Request Fields

Field	Type	Description
`isActive`	boolean	Whether nexus is active in this state
`effectiveDate`	string	ISO date when nexus becomes effective
`registrationNumber`	string	State tax registration number

Response

{
  "id": "nexus_123",
  "merchantId": "merchant_123",
  "state": "CA",
  "isActive": true,
  "effectiveDate": "2024-01-01T00:00:00Z",
  "registrationNumber": "SR-123456789",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Tax Rate Definitions

Get all active tax rate definitions for the authenticated merchant.

GET /api/tax/rate-definitions

Response

[
  {
    "id": "rate_123",
    "merchantId": "merchant_123",
    "name": "Software Services",
    "description": "Tax rate for software services",
    "taxRate": "0.0875",
    "jurisdiction": "CA",
    "category": "digital_services",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Create Tax Rate Definition

Create a new tax rate definition.

POST /api/tax/rate-definitions/create

Request Body

{
  "name": "Software Services",
  "description": "Tax rate for software services",
  "taxRate": "0.0875",
  "jurisdiction": "CA",
  "category": "digital_services",
  "isActive": true
}

Request Fields

Field	Type	Required	Description
`name`	string	✓	Name of the tax rate definition
`description`	string		Description of when this rate applies
`taxRate`	string	✓	Tax rate as decimal (0.0 to 1.0)
`jurisdiction`	string		Jurisdiction where this rate applies
`category`	string		Category of products/services this applies to
`isActive`	boolean		Whether this rate definition is active

Response

{
  "id": "rate_123",
  "merchantId": "merchant_123",
  "name": "Software Services",
  "description": "Tax rate for software services",
  "taxRate": "0.0875",
  "jurisdiction": "CA",
  "category": "digital_services",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Update Tax Rate Definition

Update an existing tax rate definition.

POST /api/tax/rate-definitions/{id}/update

Parameters

Parameter	Type	Description
`id`	string	Tax rate definition ID

Request Body

{
  "name": "Updated Software Services",
  "description": "Updated description",
  "taxRate": "0.0900",
  "jurisdiction": "CA",
  "category": "digital_services",
  "isActive": true
}

Request Fields

All fields are optional and only provided fields will be updated:

Field	Type	Description
`name`	string	Name of the tax rate definition
`description`	string	Description of when this rate applies
`taxRate`	string	Tax rate as decimal (0.0 to 1.0)
`jurisdiction`	string	Jurisdiction where this rate applies
`category`	string	Category of products/services this applies to
`isActive`	boolean	Whether this rate definition is active

Response

{
  "id": "rate_123",
  "merchantId": "merchant_123",
  "name": "Updated Software Services",
  "description": "Updated description",
  "taxRate": "0.0900",
  "jurisdiction": "CA",
  "category": "digital_services",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Get Tax Registrations

Get all active tax registrations for the authenticated merchant.

GET /api/tax/registrations

Response

[
  {
    "id": "reg_123",
    "merchantId": "merchant_123",
    "jurisdiction": "CA",
    "registrationNumber": "SR-123456789",
    "registrationType": "sales_tax",
    "effectiveDate": "2024-01-01T00:00:00Z",
    "expirationDate": "2024-12-31T23:59:59Z",
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
]

Create Tax Registration

Create a new tax registration.

POST /api/tax/registrations/create

Request Body

{
  "jurisdiction": "CA",
  "registrationNumber": "SR-123456789",
  "registrationType": "sales_tax",
  "effectiveDate": "2024-01-01T00:00:00Z",
  "expirationDate": "2024-12-31T23:59:59Z",
  "isActive": true
}

Request Fields

Field	Type	Required	Description
`jurisdiction`	string	✓	Jurisdiction of registration
`registrationNumber`	string	✓	Official registration number
`registrationType`	string	✓	Type of tax registration
`effectiveDate`	string	✓	ISO date when registration becomes effective
`expirationDate`	string		ISO date when registration expires
`isActive`	boolean		Whether registration is currently active

Response

{
  "id": "reg_123",
  "merchantId": "merchant_123",
  "jurisdiction": "CA",
  "registrationNumber": "SR-123456789",
  "registrationType": "sales_tax",
  "effectiveDate": "2024-01-01T00:00:00Z",
  "expirationDate": "2024-12-31T23:59:59Z",
  "isActive": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Calculate Tax Preview

Preview tax calculations for testing purposes without creating actual transactions.

POST /api/tax/calculate-preview

Request Body

{
  "customerId": "cust_stable_123",
  "amount": 100.0,
  "currency": "USD",
  "lineItems": [
    {
      "type": "subscription",
      "description": "Pro Plan Monthly",
      "subtotalCents": 10000,
      "componentId": "comp_123",
      "priceId": "price_123",
      "billingPeriodStart": "2024-01-01T00:00:00Z",
      "billingPeriodEnd": "2024-01-31T23:59:59Z"
    }
  ]
}

Request Fields

Field	Type	Required	Description
`customerId`	string	✓	Customer ID for tax calculation
`amount`	number	✓	Total amount to calculate tax on
`currency`	string	✓	Currency code (e.g., "USD")
`lineItems`	array		Detailed line items for calculation

Line Item Fields

Field	Type	Required	Description
`type`	string	✓	Type of line item
`description`	string	✓	Description of the line item
`subtotalCents`	number	✓	Subtotal in cents
`componentId`	string		Component ID if applicable
`priceId`	string		Price ID if applicable
`billingPeriodStart`	string	✓	Billing period start date
`billingPeriodEnd`	string	✓	Billing period end date

Response

{
  "taxAmount": 8.75,
  "taxRate": 0.0875,
  "jurisdiction": "CA",
  "breakdown": [
    {
      "type": "state",
      "rate": 0.0625,
      "amount": 6.25
    },
    {
      "type": "local",
      "rate": 0.025,
      "amount": 2.5
    }
  ],
  "exemptAmount": 0,
  "taxableAmount": 100.0
}

Examples

Enabling Automatic Tax Calculation

curl -X POST /api/tax/config/update \
  -H "Content-Type: application/json" \
  -d '{
    "autoTaxCalculation": true,
    "defaultTaxRate": "0.0875"
  }'

Setting up California Nexus

curl -X POST /api/tax/nexus/CA/update \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": true,
    "effectiveDate": "2024-01-01T00:00:00Z",
    "registrationNumber": "SR-123456789"
  }'

Creating a Tax Rate Definition

curl -X POST /api/tax/rate-definitions/create \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Software Services",
    "description": "Tax rate for digital software services",
    "taxRate": "0.0875",
    "jurisdiction": "CA",
    "category": "digital_services",
    "isActive": true
  }'

Creating a Tax Registration

curl -X POST /api/tax/registrations/create \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "CA",
    "registrationNumber": "SR-123456789",
    "registrationType": "sales_tax",
    "effectiveDate": "2024-01-01T00:00:00Z",
    "isActive": true
  }'

Preview Tax Calculation

curl -X POST /api/tax/calculate-preview \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_stable_123",
    "amount": 100.00,
    "currency": "USD",
    "lineItems": [
      {
        "type": "subscription",
        "description": "Pro Plan Monthly",
        "subtotalCents": 10000,
        "billingPeriodStart": "2024-01-01T00:00:00Z",
        "billingPeriodEnd": "2024-01-31T23:59:59Z"
      }
    ]
  }'

Getting All Tax Configurations

curl -X GET /api/tax/config \
  -H "Content-Type: application/json"

curl -X GET /api/tax/nexus \
  -H "Content-Type: application/json"

curl -X GET /api/tax/rate-definitions \
  -H "Content-Type: application/json"

curl -X GET /api/tax/registrations \
  -H "Content-Type: application/json"

Error Responses

All endpoints may return these error responses:

400 Bad Request

{
  "error": [
    {
      "code": "invalid_type",
      "message": "Tax rate must be a valid decimal number between 0 and 1 (e.g., '0.0875' for 8.75%) or null",
      "path": ["defaultTaxRate"]
    }
  ]
}

{
  "error": "Invalid US state or territory code"
}

404 Not Found

{
  "error": "Tax rate definition not found"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Important Notes

Tax Rate Format

Tax rates must be provided as decimal strings (e.g., "0.0875" for 8.75%)
Rates must be between 0.0 and 1.0 (0% to 100%)
Precision is limited to 4 decimal places (e.g., "0.0875")
Null values are acceptable for optional tax rates

State Code Validation

US state codes must be exactly 2 characters
Only valid US states and territories are accepted
State codes are automatically converted to uppercase

Automatic Configuration Creation

Tax configuration is automatically created when first updated
Nexus configurations are created per state when first updated
Default values are used when no configuration exists

Data Validation

All numeric values are validated for proper format and range
Date fields must be in ISO 8601 format
Currency codes should follow ISO 4217 standard
Line items are validated for required fields and data types

Tax Calculation Preview

Preview calculations do not create actual tax records
Used for testing tax logic before processing real transactions
Includes detailed breakdown of tax components
Respects current tax configuration and rate definitions

Merchant Isolation

All tax configurations are scoped to the authenticated merchant
Tax settings from other merchants are not accessible
Ensures complete isolation of tax configurations

Compliance Considerations

Nexus configurations help track where you have tax obligations
Tax registrations should be kept up to date with official registrations
Regular review of tax rates and configurations is recommended
Consult with tax professionals for complex tax scenarios

Historical Data

Tax configurations maintain creation and update timestamps
Soft deletion is used where applicable to preserve audit trails
Changes to tax rates do not affect historical calculations
Tax registration history is preserved for compliance purposes

Tax API

On this page