Tax Rates

Overview

Tax rates are configured per state and country. When an order is placed, the checkout system automatically looks up the applicable tax rate based on the shipping address and applies it to the order total. You can define multiple rates per region with priority ordering for compound tax scenarios.

Tax rates use soft deletion — deactivated rates are preserved for historical order records but no longer applied to new orders.

Configure Tax Rates

Create tax rates for each state or country where you collect tax. Each rate needs a name, state code, country code, and the tax percentage expressed as a decimal.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Create a tax rate for California
const rate = await whale.tax.rates.create({
  name: 'California Sales Tax',
  state: 'CA',
  country: 'US',
  rate: 0.0725,  // 7.25%
  priority: 1
})

// Response
{
  "id": "tax_550e8400-e29b-41d4-a716-446655440000",
  "name": "California Sales Tax",
  "state": "CA",
  "country": "US",
  "rate": 0.0725,
  "is_active": true,
  "priority": 1,
  "created_at": "2026-03-10T12:00:00.000Z",
  "updated_at": "2026-03-10T12:00:00.000Z"
}

// Create rates for multiple states
const states = [
  { name: 'New York Sales Tax', state: 'NY', country: 'US', rate: 0.08 },
  { name: 'Texas Sales Tax', state: 'TX', country: 'US', rate: 0.0625 },
  { name: 'Florida Sales Tax', state: 'FL', country: 'US', rate: 0.06 },
  { name: 'Washington Sales Tax', state: 'WA', country: 'US', rate: 0.065 },
]

for (const s of states) {
  await whale.tax.rates.create({ ...s, priority: 1 })
}

// List all active rates
const rates = await whale.tax.rates.list()
// { data: [...], total: 5 }

// Update a rate
await whale.tax.rates.update('tax_550e8400...', {
  rate: 0.0775,  // rate changed to 7.75%
  name: 'California Sales Tax (2026)'
})

Calculate Tax

Calculate the tax amount for a given subtotal and shipping state. The API looks up the active tax rate for the state and returns the tax amount and total. If no rate is configured for the state, tax_amount is 0.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Calculate tax for a California order
const tax = await whale.tax.calculate({
  amount: 9999,   // $99.99 in cents
  state: 'CA',
  country: 'US'
})

// Response
{
  "subtotal": 9999,
  "tax_rate": 0.0725,
  "tax_rate_name": "California Sales Tax",
  "tax_amount": 725,     // $7.25
  "total": 10724,        // $107.24
  "currency": "usd"
}

// No tax rate configured for this state
const noTax = await whale.tax.calculate({
  amount: 4999,
  state: 'MT',  // Montana — no sales tax
  country: 'US'
})

// { subtotal: 4999, tax_rate: 0, tax_rate_name: null, tax_amount: 0, total: 4999 }

// Use at checkout
const checkout = await whale.checkout.create({
  line_items: [
    { product_id: 'prod_abc123', quantity: 2 }
  ],
  shipping_address: {
    state: 'CA',
    country: 'US'
  },
  auto_tax: true  // automatically applies the matching tax rate
})

Soft Delete

Deleting a tax rate does not remove it from the database. Instead, is_active is set to false. Deactivated rates are excluded from tax calculations but remain linked to historical orders for accurate record-keeping.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Soft-delete a tax rate
await whale.tax.rates.delete('tax_550e8400...')
// The rate's is_active is now false

// It no longer appears in active listings
const active = await whale.tax.rates.list()
// Does not include the deleted rate

// But you can still retrieve it directly
const archived = await whale.tax.rates.get('tax_550e8400...')
// { id: "tax_550e8400...", is_active: false, ... }

// Include inactive rates in listing
const all = await whale.tax.rates.list({ include_inactive: true })

// Reactivate if needed
await whale.tax.rates.update('tax_550e8400...', { is_active: true })

API Reference

Tax Rate Fields