Taxes

Shopkeeper supports two approaches to handling taxes: automatic tax calculation with Stripe Tax, and manual tax rates that you define yourself.

Automatic taxes with Stripe Tax

The simplest way to handle taxes is to let Stripe calculate them for you. Enable it in your Shopkeeper configuration:

import { defineConfig } from '@foadonis/shopkeeper'

export default defineConfig({
  calculateTaxes: true,
  // ...
})

With this enabled, Stripe automatically determines the correct tax rate based on the customer's location and applies it to subscriptions, invoices, and checkout sessions.

Manual tax rates

If you prefer to manage tax rates yourself, define a taxRates method on your billable model. It should return an array of Stripe tax rate IDs:

import { compose } from '@adonisjs/core/helpers'
import { BaseModel } from '@adonisjs/lucid/orm'
import { billable } from '@foadonis/shopkeeper/mixins'

export default class User extends compose(BaseModel, billable()) {
  taxRates(): string[] {
    return ['txr_id']
  }
}

This applies the tax rate to all of the customer's subscriptions. If you need different rates per price (e.g., for subscriptions with multiple products), implement priceTaxRates:

export default class User extends compose(BaseModel, billable()) {
  priceTaxRates(): Record<string, string[]> {
    return {
      price_monthly: ['txr_id'],
      price_addon: ['txr_id_2'],
    }
  }
}

Tax exemptions

Shopkeeper provides methods to check a customer's tax exemption status:

await user.isTaxExempt()
await user.isNotTaxExempt()
await user.reverseChargeApplies()

These methods call the Stripe API and return the customer's current tax exemption status.

Going further

• Managing Subscriptions: Subscription management
• Accepting Payments: Collecting tax IDs during checkout
• Stripe Tax documentation: Stripe's complete guide to automatic tax calculation
• Stripe Tax Rates documentation: Stripe's guide to manual tax rates