Skip to content

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:

  1. TaxZone: a geographic area (country, or country + province) with a tax inclusion policy and an optional custom provider
  2. TaxRate: a percentage rate attached to a zone; one rate per zone should be marked as the default
  3. TaxRateRule: a targeting rule on a rate; when a cart line matches a rule, its rate takes priority over the zone's default
  4. TaxCalculationProvider: the service responsible for receiving a taxable item and a context, and returning TaxLine value 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

ColumnTypeDescription
country_idnullable unsignedBigIntegerThe country this zone applies to (required by the admin form)
province_codenullable stringProvince 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)
namenullable stringOptional label to identify the zone in the admin
is_tax_inclusivebooleanWhether prices already include tax (VAT) or not (sales tax). Defaults to false
provider_idnullable unsignedBigIntegerCustom tax provider; falls back to the system default when null
parent_idnullable unsignedBigIntegerParent zone, exposed through parent() and children(). The tax calculation does not use it in 2.x
metadatanullable jsonbArbitrary 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

RelationshipTypeDescription
country()BelongsToThe country this zone is scoped to
rates()HasManyAll tax rates defined for this zone
provider()BelongsToThe custom tax provider assigned to this zone
parent()BelongsToParent zone
children()HasManyChild 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

ColumnTypeDescription
tax_zone_idunsignedBigIntegerThe zone this rate belongs to
namestringDisplay name shown on invoices (TVA 20%)
codenullable stringMachine-readable identifier (FR_VAT_STANDARD)
ratedecimal(8,4)Percentage value 20.0 means 20%
is_defaultbooleanApplied when no override rule matches the item. Defaults to false
is_combinablebooleanShown as "Combinable" in the admin. The tax calculation does not read it in 2.x: an item always gets a single rate
metadatanullable jsonbArbitrary data for external providers

The TaxRate model is configurable via config/shopper/models.php (the tax_rate key).

Rate Relationships

RelationshipTypeDescription
taxZone()BelongsToThe zone this rate is attached to
rules()HasManyOverride 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_typereference_idMatches when
product_typeA 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
productA product primary key, as a stringThe item's product ID matches. For a variant in the cart, the parent product ID is used
categoryA category primary key, as a stringThe item's product is attached to that category directly (parent categories do not match)

Rule Schema

ColumnTypeDescription
idbigintPrimary key
tax_rate_idbigintFK to tax rate
reference_typestringEntity type to match (product_type, product, category)
reference_idstringEntity 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 + tax

A $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:

  1. Passes a CartLineTaxAdapter for the line to TaxCalculator::calculate()
  2. Deletes any existing CartLineTaxLine records for that line
  3. Creates new CartLineTaxLine records with the resulting tax lines
  4. Adds the line's tax to taxTotal on 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

ColumnTypeDescription
taxable_typestringPolymorphic type. CreateOrderTaxLinesAction writes OrderItem lines; OrderShipping also has a taxLines() relationship
taxable_idunsignedBigIntegerPolymorphic ID
tax_rate_idnullable unsignedBigIntegerReference to the rate used at time of purchase
codestringRate code snapshot
namestringRate name snapshot
ratedecimal(8,4)Rate percentage snapshot
amountunsignedIntegerTax 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

ColumnTypeDescription
idbigintPrimary key
identifierstringUnique provider code (e.g., avalara, taxjar)
is_enabledbooleanWhether 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:

PropertyTypeDescription
countryCodestringISO 3166-1 alpha-2 country code (FR, US, DE)
provinceCode?stringProvince or state code, matched exactly against the zone province_code (CA, NY)
customerId?intThe authenticated customer's ID, for future customer-level tax rules
resolvedZone?TaxZonePre-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:

MethodReturnDescription
getTaxableTotal()intThe line total to tax, in cents (see the adapters below for what each one includes)
getProductType()?stringProduct type value (standard, variant, virtual, external)
getProductId()?intThe 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\CartLineTaxAdapter wraps a CartLine for use during cart calculation; the taxable total is the post-discount line total in cents, and a variant line uses its parent product's ID
  • Shopper\Core\Taxes\OrderItemTaxAdapter wraps an OrderItem for use in CreateOrderTaxLinesAction; the taxable total is unit_price_amount times quantity in cents (the item's discount_amount is not subtracted), and the product ID is the item's product_id (the variant ID for a variant line, so product rules 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