Make tax treatment explicit
Choose whether hosted checkout asks the provider to calculate tax, and declare whether each price includes tax. Wildo passes those choices to the billing provider instead of calculating tax locally.
Example — Quote a business price before tax
A business offer displays its base price separately from tax. Hosted checkout asks the provider to determine the applicable tax for the purchase.
For engineers
This complete configuration example authors two inputs for an existing billing setup: the backend tax settings and a tax-exclusive monthly price. Merge taxSettings into billing.tax, and use monthlyPrice in the registered product’s prices array. Provider selection, SDK, secrets and catalogue registration are covered in billing setup and the product catalogue.
import {
TaxCalculationMode, TaxDisplayMode, type BillingConfiguration, type PriceDefinition,
} from '@wildo-ai/saas-models';
import { BillingInterval, PricingModel } from '@wildo-ai/external-connectors-models';
import { AvailableCurrency } from '@wildo-ai/zod-decorators';
export const taxSettings: NonNullable<BillingConfiguration['tax']> = {
calculationMode: TaxCalculationMode.PROVIDER_MANAGED,
defaultDisplayMode: TaxDisplayMode.EXCLUSIVE,
};
export const monthlyPrice: PriceDefinition = {
model: PricingModel.FLAT,
unitPrice: { amount: 2900n, decimals: 2, currency: AvailableCurrency.USD },
interval: BillingInterval.MONTH,
intervalCount: 1,
isDefault: true,
taxBehavior: TaxDisplayMode.EXCLUSIVE,
};
The first input makes hosted checkout request provider-managed tax calculation; Stripe receives automatic_tax.enabled. The price’s taxBehavior is sent when the price is created at the provider. USD 29 is the base price in this example; the resulting tax depends on the provider’s configured tax service and customer details.
Verify each owner’s result
| Input | Observable result |
|---|---|
PROVIDER_MANAGED calculation | The checkout session requests automatic tax |
Explicit price EXCLUSIVE | The synchronized provider price treats tax as additional to its base amount |
| Provider tax setup and customer details | The provider determines the applicable calculation |
| Application billing labels | The customer sees wording consistent with the price’s actual treatment |
Calculation and display are different controls. Disabling automatic calculation does not make a price tax-inclusive. The current catalogue sync passes the price-level value directly: there is no fallback from an unset price to product.taxDisplayMode or billing.tax.defaultDisplayMode. Author taxBehavior explicitly on each price. A global display setting does not rewrite customer-facing labels or already-created provider prices.
Use a provider test purchase to inspect the final session and invoice, rather than treating a compiled configuration as proof of a tax result. The framework delegates calculation; the provider account configuration remains an application operator responsibility.