Taxes
Configure tax zones, rates, and override rules to calculate taxes accurately per region, VAT-inclusive or sales-tax-exclusive.
Shopper calculates taxes per line item, based on where an order is being shipped. You define geographic zones, assign percentage rates to each zone, and optionally override those rates for specific products, product types, or categories. The cart pipeline applies all of this automatically during checkout.
All tax amounts are stored in cents as unsigned integers, consistent with the rest of the monetary system.
You manage zones, rates, and overrides from Settings > Taxes in the admin panel (users need the access_setting permission), or in code with the models described below.
How It Works
The tax system has four main pieces:
- TaxZone: a geographic area (country, or country + province) with a tax inclusion policy and an optional custom provider
- TaxRate: a percentage rate attached to a zone; one rate per zone should be marked as the default
- TaxRateRule: a targeting rule on a rate; when a cart line matches a rule, its rate takes priority over the zone's default
- TaxCalculationProvider: the service responsible for receiving a taxable item and a context, and returning
TaxLinevalue objects
When the cart is being calculated, the CalculateTax pipeline step reads the shipping address, resolves the matching TaxZone, picks the applicable TaxRate, and stores a CartLineTaxLine record for each tax line returned for a cart line. A matching 0% rate still produces a record, with an amount of 0.
Tax Zones
A tax zone defines where a tax configuration applies. It maps to a country and optionally to a specific province or state within that country. The most important setting on a zone is is_tax_inclusive, which determines whether prices already include tax (VAT, common in Europe) or whether tax is added on top (sales tax, common in the US).
use Shopper\Core\Models\Country;
use Shopper\Core\Models\TaxZone;
$france = Country::query()->where('cca2', 'FR')->firstOrFail();
$franceZone = TaxZone::query()->create([
'country_id' => $france->id,
'name' => 'Standard VAT',
'is_tax_inclusive' => true,
]);$usa = Country::query()->where('cca2', 'US')->firstOrFail();
TaxZone::query()->create([
'country_id' => $usa->id,
'province_code' => 'CA',
'name' => 'California Sales Tax',
'is_tax_inclusive' => false,
]);When the calculator resolves a zone for a shipping address, it first tries to find a zone matching both the country and province. If none exists, it falls back to a country-level zone with no province_code. The country is matched on its cca2 code, and the province with an exact string comparison against the state of the cart shipping address.
The display_name accessor returns a human-readable label: the translated country name, followed by the zone name when the zone has one.
Zone Schema
| Column | Type | Description |
|---|---|---|
country_id | nullable unsignedBigInteger | The country this zone applies to (required by the admin form) |
province_code | nullable string | Province or state code, compared as an exact string with the cart address state. Use the format your checkout stores (CA, or the ISO 3166-2 US-CA the admin suggests) |
name | nullable string | Optional label to identify the zone in the admin |
is_tax_inclusive | boolean | Whether prices already include tax (VAT) or not (sales tax). Defaults to false |
provider_id | nullable unsignedBigInteger | Custom tax provider; falls back to the system default when null |
parent_id | nullable unsignedBigInteger | Parent zone, exposed through parent() and children(). The tax calculation does not use it in 2.x |
metadata | nullable jsonb | Arbitrary data for custom providers |
The combination of country_id and province_code is unique, you cannot have two zones for the same country/province pair. Unique indexes treat NULL values as distinct, so this does not cover country-level zones: create only one zone without province_code per country, because the calculator uses the first one it finds. The TaxZone model is configurable via config/shopper/models.php (the tax_zone key).
Zone Relationships
| Relationship | Type | Description |
|---|---|---|
country() | BelongsTo | The country this zone is scoped to |
rates() | HasMany | All tax rates defined for this zone |
provider() | BelongsTo | The custom tax provider assigned to this zone |
parent() | BelongsTo | Parent zone |
children() | HasMany | Child zones |
Tax Rates
Each zone has one or more rates. Mark one rate per zone as is_default: it applies to every item in the zone that does not match a more specific override rule. Shopper does not enforce a single default; if several rates of a zone have the flag, the first one loaded is used. If a zone has no default rate, items that match no rule get no tax line.
use Shopper\Core\Models\TaxRate;
TaxRate::query()->create([
'tax_zone_id' => $franceZone->id,
'name' => 'TVA 20%',
'code' => 'FR_VAT_STANDARD',
'rate' => 20.0,
'is_default' => true,
]);France has a reduced VAT rate of 5.5% on food. You can define it as a separate non-default rate on the same zone, then target it at the right product category using a rule:
$reducedRate = TaxRate::query()->create([
'tax_zone_id' => $franceZone->id,
'name' => 'TVA 5.5%',
'code' => 'FR_VAT_REDUCED',
'rate' => 5.5,
'is_default' => false,
]);Tax Rate Schema
| Column | Type | Description |
|---|---|---|
tax_zone_id | unsignedBigInteger | The zone this rate belongs to |
name | string | Display name shown on invoices (TVA 20%) |
code | nullable string | Machine-readable identifier (FR_VAT_STANDARD) |
rate | decimal(8,4) | Percentage value 20.0 means 20% |
is_default | boolean | Applied when no override rule matches the item. Defaults to false |
is_combinable | boolean | Shown as "Combinable" in the admin. The tax calculation does not read it in 2.x: an item always gets a single rate |
metadata | nullable jsonb | Arbitrary data for external providers |
The TaxRate model is configurable via config/shopper/models.php (the tax_rate key).
Rate Relationships
| Relationship | Type | Description |
|---|---|---|
taxZone() | BelongsTo | The zone this rate is attached to |
rules() | HasMany | Override rules that activate this rate for specific items |
Tax Rate Rules
Rules let you override the default rate for specific items. The calculator goes through the zone's rates that have at least one rule, in the order the database returns them, and uses the first rate with a rule that matches the line. If no rule matches, the zone's default rate is used. In the admin, an override (Create Override on a zone) is a non-default rate with its rules.
A rule has two fields: reference_type identifies what kind of entity to match, and reference_id holds the specific value to match against.
use Shopper\Core\Models\TaxRateRule;
TaxRateRule::query()->create([
'tax_rate_id' => $reducedRate->id,
'reference_type' => 'category',
'reference_id' => (string) $foodCategory->id,
]);This rule tells the calculator: "whenever a cart line belongs to the food category, use the 5.5% rate instead of the default 20%."
You can also target a specific product:
TaxRateRule::query()->create([
'tax_rate_id' => $zeroVatRate->id,
'reference_type' => 'product',
'reference_id' => (string) $childrenBook->id,
]);Or an entire product type, which is useful for applying different rules to virtual goods versus physical ones:
TaxRateRule::query()->create([
'tax_rate_id' => $digitalRate->id,
'reference_type' => 'product_type',
'reference_id' => 'virtual',
]);Rule Reference Types
reference_type | reference_id | Matches when |
|---|---|---|
product_type | A ProductType enum value (standard, variant, virtual, external; the admin offers all but variant) | The item's product type equals the value. For a variant, the parent product's type is used |
product | A product primary key, as a string | The item's product ID matches. For a variant in the cart, the parent product ID is used |
category | A category primary key, as a string | The item's product is attached to that category directly (parent categories do not match) |
Rule Schema
| Column | Type | Description |
|---|---|---|
id | bigint | Primary key |
tax_rate_id | bigint | FK to tax rate |
reference_type | string | Entity type to match (product_type, product, category) |
reference_id | string | Entity value or ID to match against |
The combination of tax_rate_id, reference_type, and reference_id is unique. You cannot attach the same rule twice to the same rate.
Inclusive vs Exclusive Taxes
The is_tax_inclusive flag on the zone controls the math behind the tax amount.
Tax-exclusive (sales tax): tax is added on top of the price. The customer pays more than the listed price:
tax = line_total * rate / 100
total = line_total + taxA $100 product with a 10% exclusive tax costs $110 at checkout.
Tax-inclusive (VAT): tax is already embedded in the listed price. The customer pays exactly the listed price, but the tax authority receives a portion:
tax = line_total - (line_total / (1 + rate / 100))
total = line_total (unchanged)A €100 product with 20% VAT inclusive: tax = €100 - (€100 / 1.2) = €16.67, amount before tax = €83.33.
Shopper handles both formulas automatically in SystemTaxProvider. The tax is computed on the whole line total (not per unit) and rounded to the nearest cent. The zone's is_tax_inclusive value is also propagated to the taxInclusive property of the cart pipeline context, so storefronts can show "VAT included" or display tax as an addition at checkout.
Cart Integration
Tax calculation is part of the cart pipeline (the shopper.cart.pipelines.cart config key) and runs automatically whenever you call CartManager::calculate(). The CalculateTax step runs after discounts are applied, ensuring taxes are computed on the post-discount amount.
The step reads the country (cca2) and state of the cart's shipping address and builds a TaxCalculationContext from those values and the cart's customer_id. Then, for each cart line whose taxable amount (line subtotal minus its discount adjustments) is above zero, it:
- Passes a
CartLineTaxAdapterfor the line toTaxCalculator::calculate() - Deletes any existing
CartLineTaxLinerecords for that line - Creates new
CartLineTaxLinerecords with the resulting tax lines - Adds the line's tax to
taxTotalon the pipeline context
Finally, it sets taxInclusive on the context from the resolved zone. Each CartLineTaxLine stores the code, name, rate, amount (in cents), and tax_rate_id of a tax line.
use Shopper\Cart\CartManager;
$context = resolve(CartManager::class)->calculate($cart);
$context->taxTotal;
$context->taxInclusive;
$cart->load('lines.taxLines');
foreach ($cart->lines as $line) {
foreach ($line->taxLines as $taxLine) {
$taxLine->name;
$taxLine->amount;
}
}The pipeline loads lines.taxLines before CalculateTax replaces the records, so reload the relation (as above) to read the new tax lines.
If the cart has no shipping address with a country, the CalculateTax step is skipped. If no tax zone matches the address, no tax lines are created and taxTotal stays 0.
Persisting Tax Lines on Orders
When CreateOrderFromCartAction converts a cart into an order, it calls CreateOrderTaxLinesAction, which stores the tax lines of each order item. Each line copies the rate code, name, and percentage, so future changes to zones or rates have no impact on historical orders.
use Shopper\Core\Actions\CreateOrderTaxLinesAction;
app(CreateOrderTaxLinesAction::class)->execute($order);The action resolves the shipping address country (from the address country_name), runs TaxCalculator::calculate() for each order item, creates an OrderTaxLine record for each result, and updates tax_amount on both the order item and the order itself. It does not delete existing tax lines, so run it only once per order.
The action recalculates taxes from the order items instead of copying the cart tax lines. Its context has no province, so only country-level zones apply, and each item is taxed on unit_price_amount times quantity, before its discount_amount. When the cart used a province zone or a discount, the order's tax_amount can differ from the cart's taxTotal.
OrderTaxLine Schema
| Column | Type | Description |
|---|---|---|
taxable_type | string | Polymorphic type. CreateOrderTaxLinesAction writes OrderItem lines; OrderShipping also has a taxLines() relationship |
taxable_id | unsignedBigInteger | Polymorphic ID |
tax_rate_id | nullable unsignedBigInteger | Reference to the rate used at time of purchase |
code | string | Rate code snapshot |
name | string | Rate name snapshot |
rate | decimal(8,4) | Rate percentage snapshot |
amount | unsignedInteger | Tax amount in cents |
The Shopper\Core\Models\OrderTaxLine model has a taxable() morph relationship and a taxRate() relationship.
Accessing Tax Lines on an Order
The order itself has no taxLines() relationship: load the tax lines through its items, and read the order total from tax_amount.
use Shopper\Core\Models\Contracts\Order;
$order = resolve(Order::class)::query()
->with('items.taxLines')
->find($orderId);
$order->tax_amount;
foreach ($order->items as $item) {
$item->tax_amount;
foreach ($item->taxLines as $taxLine) {
$taxLine->name;
$taxLine->rate;
$taxLine->amount;
}
}Tax Providers
A TaxProvider record links a zone to a custom tax calculation service. When a zone has an enabled provider, the calculator uses that provider instead of the built-in system.
Provider Schema
| Column | Type | Description |
|---|---|---|
id | bigint | Primary key |
identifier | string | Unique provider code (e.g., avalara, taxjar) |
is_enabled | boolean | Whether the provider is active. Defaults to true |
The Shopper\Core\Models\TaxProvider model has a taxZones() relationship and an isEnabled() method. The admin has no screen to manage providers: create the records in code or in a seeder. The tax zone form then lists the enabled ones in its Tax provider select.
Custom Tax Providers
The built-in SystemTaxProvider handles most use cases. For regions that require an external API like Avalara, TaxJar, or a homegrown tax service, you can implement the TaxCalculationProvider contract and assign it to specific zones.
The contract is simple:
namespace Shopper\Core\Contracts;
use Shopper\Core\Taxes\TaxCalculationContext;
use Shopper\Core\Taxes\TaxLine;
interface TaxCalculationProvider
{
public function identifier(): string;
/** @return array<int, TaxLine> */
public function getTaxLines(TaxableItem $item, TaxCalculationContext $context): array;
}Here is a complete implementation that calls a fictional external tax API:
use Shopper\Core\Contracts\TaxCalculationProvider;
use Shopper\Core\Contracts\TaxableItem;
use Shopper\Core\Taxes\TaxCalculationContext;
use Shopper\Core\Taxes\TaxLine;
final class AvalaraTaxProvider implements TaxCalculationProvider
{
public function __construct(
private readonly AvalaraClient $client,
) {}
public function identifier(): string
{
return 'avalara';
}
public function getTaxLines(TaxableItem $item, TaxCalculationContext $context): array
{
$defaultRate = $context->resolvedZone->rates()
->where('is_default', true)
->firstOrFail();
$response = $this->client->calculate(
amount: $item->getTaxableTotal(),
countryCode: $context->countryCode,
provinceCode: $context->provinceCode,
);
return [
new TaxLine(
taxRateId: $defaultRate->id,
name: $response->description,
code: $response->jurisdictionCode,
rate: $response->rate,
amount: $response->taxAmountInCents,
),
];
}
}taxRateId must be the ID of an existing tax rate: cart and order tax lines store it in a tax_rate_id foreign key. The example uses the zone's default rate, so the zone needs one.
TaxCalculator gets its providers from the container under the TaxCalculationProvider contract. It resolves its default provider once, without parameters. For a zone linked to an enabled TaxProvider, it resolves the contract again and passes the record's identifier as a provider parameter. Bind the contract to a closure that reads that parameter, in the register() method of a service provider:
use Shopper\Core\Contracts\TaxCalculationProvider;
use Shopper\Core\Taxes\SystemTaxProvider;
$this->app->bind(
TaxCalculationProvider::class,
fn ($app, array $parameters): TaxCalculationProvider => match ($parameters['provider'] ?? null) {
'avalara' => $app->make(AvalaraTaxProvider::class),
default => $app->make(SystemTaxProvider::class),
},
);The identifier() method of your class does not select it: the match on the provider parameter does. Binding the contract directly to your class (bind(TaxCalculationProvider::class, AvalaraTaxProvider::class)) would replace SystemTaxProvider for every zone, including zones without a provider.
Then create a TaxProvider record and link it to the zone that should use it:
use Shopper\Core\Models\TaxProvider;
$provider = TaxProvider::query()->create([
'identifier' => 'avalara',
'is_enabled' => true,
]);
$usZone->update(['provider_id' => $provider->id]);When the calculator resolves a zone that has an enabled provider, it resolves that provider from the container instead of using the system default. Zones without a provider, or with a disabled one, use SystemTaxProvider. TaxCalculator is a singleton that caches the zone and the provider for each country/province combination, so each combination is resolved once per request. In a queue worker, these caches (and the rates SystemTaxProvider caches per zone) last until the worker restarts.
The TaxCalculationContext
The TaxCalculationContext is a read-only value object that carries the geographic information needed to resolve the correct zone and provider:
| Property | Type | Description |
|---|---|---|
countryCode | string | ISO 3166-1 alpha-2 country code (FR, US, DE) |
provinceCode | ?string | Province or state code, matched exactly against the zone province_code (CA, NY) |
customerId | ?int | The authenticated customer's ID, for future customer-level tax rules |
resolvedZone | ?TaxZone | Pre-resolved zone; set internally by the calculator to avoid redundant queries |
The TaxableItem Contract
Any object you pass to TaxCalculator::calculate() must implement Shopper\Core\Contracts\TaxableItem:
| Method | Return | Description |
|---|---|---|
getTaxableTotal() | int | The line total to tax, in cents (see the adapters below for what each one includes) |
getProductType() | ?string | Product type value (standard, variant, virtual, external) |
getProductId() | ?int | The product's primary key |
getCategoryIds() | array<int, int> | Primary keys of the categories the product is attached to |
The contract exposes a single getTaxableTotal() rather than a separate unit amount and quantity. The provider taxes that total in one pass, so a line whose total is not evenly divisible by its quantity is never rounded per unit. This keeps exclusive zones from overcharging by a cent and keeps inclusive VAT breakdowns balanced (net plus tax always equals gross).
Shopper ships two ready-made adapters:
Shopper\Cart\Taxes\CartLineTaxAdapterwraps aCartLinefor use during cart calculation; the taxable total is the post-discount line total in cents, and a variant line uses its parent product's IDShopper\Core\Taxes\OrderItemTaxAdapterwraps anOrderItemfor use inCreateOrderTaxLinesAction; the taxable total isunit_price_amounttimesquantityin cents (the item'sdiscount_amountis not subtracted), and the product ID is the item'sproduct_id(the variant ID for a variant line, soproductrules do not match it)
If you are building a custom checkout flow or need to calculate taxes outside of a cart, you can implement TaxableItem directly on any of your objects and call TaxCalculator::calculate() with a manually constructed TaxCalculationContext. TaxCalculator is registered as a singleton, so resolve it from the container:
use Shopper\Core\Taxes\TaxCalculationContext;
use Shopper\Core\Taxes\TaxCalculator;
$calculator = resolve(TaxCalculator::class);
$taxLines = $calculator->calculate(
$item,
new TaxCalculationContext(countryCode: 'US', provinceCode: 'CA'),
);
foreach ($taxLines as $taxLine) {
$taxLine->name;
$taxLine->rate;
$taxLine->amount;
}calculateMany(array $items, TaxCalculationContext $context) returns the tax lines of several items at once, keyed like the input array, and resolveZone(TaxCalculationContext $context) returns the matching TaxZone, or null.
Last updated on
Edit on GitHub