Tax Rates

Overview

Tax Rates define the VAT/sales tax percentages applied to menu items. Different items may have different tax rates (e.g., food vs. alcohol).

Key Purpose: Configure tax rates for accurate pricing and compliance.

Purpose

This page lets you create, edit, and manage VAT/sales tax rates that are applied to menu items for accurate pricing and receipt tax breakdowns.

Key Concepts

Custom Tax Rates: Merchant-created rates stored per location with a name, percentage, and unique category code generated from the category name.
Standard Tax Rates: Country-level default rates maintained by the system (e.g., 9% food VAT in NL); custom rates override or supplement these.
Category Code: An uppercase, alphanumeric code auto-derived from the tax rate name (e.g., "Food" becomes "FOOD"); must be unique across both standard and custom rates for a location.
Location-Country Binding: Each tax rate is associated with a location, and the system resolves the country code from the location via LocationService to load the correct standard rates.
In-Use Protection: A tax rate that is currently assigned to menu items cannot be deleted; the backend returns a 409 conflict error.

Actions

Create a Tax Rate

Define a new custom tax rate with a category name and percentage; the system generates a unique category code and validates it does not duplicate an existing rate.

Edit a Tax Rate

Update the percentage or name of an existing custom tax rate; the category code and location binding are preserved.

Delete a Tax Rate

Remove a custom tax rate that is no longer needed; deletion is blocked if any menu items still reference the rate.

Location

Backoffice Route: /settings/tax-rates
Backend Controller: app/Http/Controllers/Api/TaxRateController.php
Vue Component: src/views/settings/TaxRatesComponent.vue

Fields

Tax Rate Name

Property	Value
Field ID	`name`
Label	Name
Type	Text
Required	Yes
Validation	max: 50 characters

Description: Name for this tax rate (internal reference).

Examples:

"Standard VAT"
"Reduced VAT"
"Food"
"Alcohol"
"Zero Rate"

Tax Percentage

Property	Value
Field ID	`percentage`
Label	Tax Rate %
Type	Number
Required	Yes
Validation	min: 0, max: 100

Description: The tax percentage to apply.

Examples:

21% - Standard VAT (Netherlands, Belgium)
9% - Reduced VAT for food (Netherlands)
6% - Reduced VAT (Belgium)
19% - Standard VAT (Germany)
7% - Reduced VAT (Germany)
0% - Zero rate (exports, exempt items)

Default Rate

Property	Value
Field ID	`is_default`
Label	Default Rate
Type	Toggle
Default	false

Description: Whether this is the default tax rate for new items.

Business Logic:

Only one rate can be default
New items automatically use default rate
Can be overridden per item

Active

Property	Value
Field ID	`active`
Label	Active
Type	Toggle
Default	true

Description: Whether this tax rate is available for use.

Common Tax Rates by Country

Netherlands (NL)

Rate	Percentage	Use
Standard	21%	Alcohol, non-food
Reduced	9%	Food, drinks
Zero	0%	Exempt items

Belgium (BE)

Rate	Percentage	Use
Standard	21%	Alcohol, non-food
Reduced	6%	Food, drinks
Intermediate	12%	Some services
Zero	0%	Exempt items

Germany (DE)

Rate	Percentage	Use
Standard	19%	Most items
Reduced	7%	Food, drinks
Zero	0%	Exempt items

France (FR)

Rate	Percentage	Use
Standard	20%	Most items
Intermediate	10%	Restaurant food
Reduced	5.5%	Takeaway food
Zero	0%	Exempt items

UK (GB)

Rate	Percentage	Use
Standard	20%	Most items
Reduced	5%	Some items
Zero	0%	Most food

Business Logic

Tax Calculation

Item Price (excl. tax): €10.00
Tax Rate: 9%

Tax Amount = €10.00 × 0.09 = €0.90
Price (incl. tax) = €10.00 + €0.90 = €10.90

OR if prices entered including tax:
Price (incl. tax): €10.90
Tax Rate: 9%
Tax Amount = €10.90 - (€10.90 / 1.09) = €0.90
Price (excl. tax) = €10.00

Tax on Order

Order Items:
├── Pizza (9% tax): €12.00 → Tax: €1.08
├── Beer (21% tax): €4.00 → Tax: €0.84
└── Dessert (9% tax): €6.00 → Tax: €0.54

Subtotal: €22.00
Total Tax: €2.46
Total: €24.46

Receipt shows:
- 9% VAT: €1.62 (on €18.00)
- 21% VAT: €0.84 (on €4.00)

Dine-in vs Takeaway Tax

Some countries have different tax rates for dine-in vs takeaway:

France Example:
- Dine-in food: 10%
- Takeaway food: 5.5%

System can automatically apply correct rate based on dining option.

Customer Impact

Price Display

Setting	Customer Sees
Prices incl. tax	€10.90
Prices excl. tax	€10.00 + tax

Most B2C businesses display prices including tax.

Receipt

Receipt shows tax breakdown:

Subtotal:        €22.00
VAT 9%:           €1.62
VAT 21%:          €0.84
─────────────────────────
Total:           €24.46

Relations

Depends On

Locations: Tax rates can be per-location (different countries)

Affects

Menu Items: Each item has a tax rate
Transactions: Tax calculated on orders
Reports: Tax reporting
Receipts: Tax breakdown

Business Rules

The category code is auto-generated as an uppercase version of the category name with non-alpha characters replaced by underscores; it must be unique per location across both custom and standard rate repositories.
A tax rate cannot be deleted if it is currently assigned to any menu item (isBeingUsed check); attempting to do so returns a 409 error with the message "Cannot delete tax rate that is being used."
Tax rates are scoped to a location, and the country code is resolved from the location's address via LocationService.retrieve().getCountryCode().
Custom tax rates use the source value CUSTOM to distinguish them from system-provided standard rates for the same country.
The tax percentage must be between 0 and 100 inclusive; the system supports zero-rate entries for exempt items.

FAQs

"Why can I not delete a tax rate?" The rate is still assigned to one or more menu items; reassign those items to a different rate before deleting.
"Can I have multiple tax rates with the same percentage?" Yes, as long as the category names (and therefore category codes) are different, you can have multiple rates at the same percentage.
"Are standard country rates editable?" No, system-provided standard rates cannot be modified; create a custom rate if you need a different value.
"What happens if I change a tax rate percentage?" Existing menu items using that rate will apply the new percentage on all future orders; past transactions retain the rate at the time of sale.
"Do tax rates apply across all locations?" No, each tax rate is tied to a specific location and its country; multi-location setups require configuring rates per location.

Troubleshooting

Problem: Wrong tax being applied

Causes:

Item has wrong tax rate assigned
Default rate incorrect
Location tax settings

Solutions:

Check item's tax rate setting
Verify default tax rate
Review location settings

Problem: Tax not showing on receipt

Causes:

Tax rate is 0%
Receipt settings
Tax display disabled

Solutions:

Check tax rate percentage
Review receipt configuration
Enable tax display

Problem: Prices seem wrong

Causes:

Prices entered excl. tax but displayed incl. tax
Tax rate changed after prices set
Rounding differences

Solutions:

Clarify price entry method
Update prices after tax changes
Review rounding settings

Examples

Netherlands Setup

json

{
  "tax_rates": [
    {
      "name": "Food (9%)",
      "percentage": 9,
      "is_default": true,
      "active": true
    },
    {
      "name": "Alcohol (21%)",
      "percentage": 21,
      "is_default": false,
      "active": true
    },
    {
      "name": "Zero Rate",
      "percentage": 0,
      "is_default": false,
      "active": true
    }
  ]
}

Belgium Setup

json

{
  "tax_rates": [
    {
      "name": "Food (6%)",
      "percentage": 6,
      "is_default": true,
      "active": true
    },
    {
      "name": "Alcohol (21%)",
      "percentage": 21,
      "is_default": false,
      "active": true
    }
  ]
}

Germany Setup

json

{
  "tax_rates": [
    {
      "name": "Reduced (7%)",
      "percentage": 7,
      "is_default": true,
      "active": true
    },
    {
      "name": "Standard (19%)",
      "percentage": 19,
      "is_default": false,
      "active": true
    }
  ]
}

Item Tax Assignment

json

{
  "items": [
    {
      "name": "Margherita Pizza",
      "price": 12.50,
      "tax_rate_id": "food-9"
    },
    {
      "name": "House Wine",
      "price": 18.00,
      "tax_rate_id": "alcohol-21"
    },
    {
      "name": "Sparkling Water",
      "price": 3.50,
      "tax_rate_id": "food-9"
    }
  ]
}

Legal Compliance

VAT Registration

Businesses above threshold must register for VAT
VAT number must be displayed on receipts
Regular VAT returns required

Record Keeping

Keep records of all transactions
Tax breakdown must be accurate
Receipts must show VAT amounts

Rate Changes

Monitor for tax rate changes
Update rates promptly when changed
May need to adjust prices

Note: Tax regulations vary by country. Consult a tax professional for compliance advice.

Tax Rates ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Create a Tax Rate ​

Edit a Tax Rate ​

Delete a Tax Rate ​

Location ​

Fields ​

Tax Rate Name ​

Tax Percentage ​

Default Rate ​

Active ​

Common Tax Rates by Country ​

Netherlands (NL) ​

Belgium (BE) ​

Germany (DE) ​

France (FR) ​

UK (GB) ​

Business Logic ​

Tax Calculation ​

Tax on Order ​

Dine-in vs Takeaway Tax ​

Customer Impact ​

Price Display ​

Receipt ​

Relations ​

Depends On ​

Affects ​

Related Features ​

Business Rules ​

FAQs ​

Troubleshooting ​

Problem: Wrong tax being applied ​

Problem: Tax not showing on receipt ​

Problem: Prices seem wrong ​

Examples ​

Netherlands Setup ​

Belgium Setup ​

Germany Setup ​

Item Tax Assignment ​

Legal Compliance ​

VAT Registration ​

Record Keeping ​

Rate Changes ​

Tax Rates

Overview

Purpose

Key Concepts

Actions

Create a Tax Rate

Edit a Tax Rate

Delete a Tax Rate

Location

Fields

Tax Rate Name

Tax Percentage

Default Rate

Active

Common Tax Rates by Country

Netherlands (NL)

Belgium (BE)

Germany (DE)

France (FR)

UK (GB)

Business Logic

Tax Calculation

Tax on Order

Dine-in vs Takeaway Tax

Customer Impact

Price Display

Receipt

Relations

Depends On

Affects

Related Features

Business Rules

FAQs

Troubleshooting

Problem: Wrong tax being applied

Problem: Tax not showing on receipt

Problem: Prices seem wrong

Examples

Netherlands Setup

Belgium Setup

Germany Setup

Item Tax Assignment

Legal Compliance

VAT Registration

Record Keeping

Rate Changes