When it runs
Tax is calculated once, while the order is created, and the resulting lines are stored on the order. They’re included ingetTotalPrice(), so every payment gateway charges the taxed amount without doing anything extra.
If the configured engine can’t be resolved, Aikeedo falls back to the null engine, so a missing plugin never blocks checkout.
The interface
TaxResult is a list of Billing\Domain\ValueObjects\TaxLine objects:
percent line, checkout and the purchase emails show the rate after the name, as in “VAT (20%)”, so don’t repeat it in name.
TaxResult::getTaxTotal() sums the lines, so return several when a jurisdiction has more than one component, such as a state and a city tax.
Implementation
src/FlatTaxEngine.php
Rules to follow
- Return an empty
TaxResult()when you can’t calculate, including when an external service fails. Throwing blocks checkout entirely. - Work in minor units. Round once, at the end.
- Respect the tax base. Administrators choose it under Settings → Billing → Tax, stored in
option.billing.tax_base:discounted_line(the default) taxes the amount after the coupon, andlist_pricetaxes the full plan price. Read it, or document which base your engine always uses. - Handle a missing address. Many workspaces have none, and a plan may be sold without one.
- Don’t call a slow API without a timeout. Order creation waits for you.
Business buyers
Checkout lets the customer buy as a business. The workspace address,Workspace\Domain\ValueObjects\Address, carries what you need for B2B rules such as a reverse charge on cross-border sales:
Register it
src/Plugin.php
option.billing.tax_engine. Every installed engine is also listed under Settings → Finance → Tax engines, which links to each engine’s settings page.
The settings page
Both the Configure selected engine link on the billing page and the Tax engines list point to/admin/settings/tax-engines/{key}, so declare that route:
extra.default_url to the same path. For the form itself, see Admin settings pages.
Using an external tax service
For a service such as a rate API, keep the network call tight:Testing
Checkout shows your tax lines, and the total includes them.
A workspace without an address still reaches checkout.
A zero or missing rate produces no tax line at all.
A discounted order taxes the amount you intended.
With the service unreachable, checkout still completes.