# Tax

Pick one tax source per Channel. Use the EU's daily rates, or bring your own amounts.

Every Channel has exactly one tax source. OrbCart never guesses a rate from a
product name or the kind of goods, and never falls back to another source. If tax cannot be
determined, there is no Quote. Your business stays responsible for how each
Offer is classified.

## Choose a source

| Channel setting      | Use it when                                                   | Who calculates                                 |
| -------------------- | ------------------------------------------------------------- | ---------------------------------------------- |
| `tax: "eu-standard"` | You sell to EU countries.                                     | OrbCart, with the EU's daily national rates.   |
| `tax: yourFunction`  | Non-EU markets, or your ERP or tax service decides.           | You return complete amounts.                   |
| _no setting_         | You sell to EU countries and want a tax estimate in the cart. | OrbCart, with its own table of national rates. |

Both EU sources know all 27 member states and the same tax categories. They
differ in where the rates come from:

- **`eu-standard`** imports the rates from the EU's TEDB once a day. A rate
  change applies on the day it takes effect, without an OrbCart update. Tax
  appears from the Quote on, and each tax line names the import, such as
  `eu-tedb@2026-11-03`.
- **No setting** uses the table that ships with OrbCart, so the cart already
  estimates tax. A rate change needs an OrbCart update. Each tax line names the
  table's version, such as `eu-vat-rates@2026-07-01`.

## Tax categories

Give every Offer a `taxCategory`, usually on its Type in the catalog. A
category names one of a country's rates, never a kind of goods:

| Category        | Rate                                     |
| --------------- | ---------------------------------------- |
| `standard`      | The national standard rate.              |
| `reduced`       | The lower reduced rate, at least 5 %.    |
| `intermediate`  | The higher of two reduced rates.         |
| `super_reduced` | The rate below 5 %.                      |
| `zero`          | 0 %, with the right to deduct input VAT. |
| `exempt`        | 0 %, exempt from VAT.                    |

The same goods can sit in different categories in different countries. A book
is `reduced` in Germany and France, but `super_reduced` in Italy and Spain. If
your Offers need such a split, use a tax function for those countries.

A category a country does not have means no Quote for that buyer, naming the
country and the category. OrbCart never falls back to the standard rate, with one
exception the law makes: a country with no reduced rate at all, Denmark, taxes
everything at its standard rate, so every category is 25 % there.

If TEDB sends no national reduced-rate rows for another member state, those categories remain
unknown and checkout refuses them. Missing rows never establish that a country has no reduced VAT.

| Country | `standard` | `reduced` | `intermediate` | `super_reduced` |
| ------- | ---------- | --------- | -------------- | --------------- |
| AT      | 20         | 10        | 13             | 4.9             |
| BE      | 21         | 6         | 12             |                 |
| BG      | 20         | 9         |                |                 |
| CY      | 19         | 5         | 9              | 3               |
| CZ      | 21         | 12        |                |                 |
| DE      | 19         | 7         |                |                 |
| DK      | 25         | 25        | 25             | 25              |
| EE      | 24         | 9         | 13             |                 |
| ES      | 21         | 10        |                | 4               |
| FI      | 25.5       | 10        | 13.5           |                 |
| FR      | 20         | 5.5       | 10             | 2.1             |
| GR      | 24         | 6         | 13             | 4               |
| HR      | 25         | 5         | 13             |                 |
| HU      | 27         | 5         | 18             |                 |
| IE      | 23         | 9         | 13.5           |                 |
| IT      | 22         | 5         | 10             | 4               |
| LT      | 21         | 5         | 12             |                 |
| LU      | 17         | 8         | 14             | 3               |
| LV      | 21         | 5         | 12             |                 |
| MT      | 18         | 5         | 7              |                 |
| NL      | 21         | 9         |                |                 |
| PL      | 23         | 5         | 8              |                 |
| PT      | 23         | 6         | 13             |                 |
| RO      | 21         | 11        |                |                 |
| SE      | 25         | 6         | 12             |                 |
| SI      | 22         | 5         | 9.5            |                 |
| SK      | 23         | 5         | 19             |                 |

Rates as of November 2026, in percent. With `eu-standard`, the day's import
decides. Regional rates, such as Corsica's or the Azores', are not offered.
Neither are parking rates: each equals a reduced rate of its country, except
Malta's 12 %, which applies to services only.

## EU standard VAT

### Opt in on the Channel

```ts title="src/worker.ts" members="Channels"
de: {
  currency: "EUR",
  pricesIncludeTax: true,
  locale: "de-DE",
  tax: "eu-standard",
  shipping: { DE: [standard], AT: [standard], FR: [standard] },
},
```

Every [tax category](#tax-categories) is quoted at the day's national rate.
### Add the Cron trigger

```jsonc title="wrangler.jsonc"
"triggers": { "crons": ["*/15 * * * *"] }
```

This does **not** call the EU every 15 minutes. It imports once a day, around
20:00 UTC, and uses the other runs only to retry a failed import.
### Prime and check the first import

After the first deploy, from your Worker's directory:

```sh
pnpm exec orbcart tax sync --env test
pnpm exec orbcart tax status --env test
```

Add `--worker <name>` if the deployed Worker is not `<wrangler name>-test`, and
`--config <path>` for a non-default config file.

### Read tax status

| `state`     | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `ready`     | Today's import completed.                                         |
| `waiting`   | Today's rates are there. The next import is not due yet.          |
| `retrying`  | The import failed and will try again (after 15, 30, 60, 120 min). |
| `exhausted` | Today's import gave up. Check the Worker logs.                    |

Before real orders, check that `availableOn` includes today. `missing` lists
countries without a clear rate. Only buyers there get no Quote.

`tax sync` exits with an error unless rates for today are available, so a setup
script can rely on it. `tax status` always exits 0. Read its output.

### Where eu-standard applies

All 27 EU member states, at their national rates. Shipping to a non-EU
country, such as Switzerland, Norway or the UK, fails at startup. Use a tax
function there.

Special territories outside EU VAT get no Quote. The checkout asks for the
postal code where it matters:

| Country | Excluded                                                                                        |
| ------- | ----------------------------------------------------------------------------------------------- |
| DE      | Heligoland, Büsingen                                                                            |
| AT      | Jungholz, Mittelberg                                                                            |
| ES      | Canary Islands, Ceuta, Melilla                                                                  |
| FR      | Overseas departments and collectivities (postal codes 97, 984 to 989). Monaco counts as France. |
| IT      | Livigno, Campione d'Italia                                                                      |
| PT      | Madeira, Azores                                                                                 |
| FI      | Åland                                                                                           |
| GR      | Mount Athos                                                                                     |
| CY      | Kyrenia district                                                                                |

## Work performed at your Location

A stand-alone valuation of or work on a consumer's own movable goods, physically
performed at one of your Locations, is taxed where that Location is (Art. 54(2)(b)
of the VAT Directive), wherever the buyer lives. A ski service in your Munich
workshop costs German VAT for a buyer from Vienna.

Mark such an Offer with `supply`, and send the Location as your catalog's public
`/v1/locations` delivers it. Look it up there by its ID and take only its `id`,
`name` and `address`, not the whole delivery response. Never copy a buyer's
configuration into it.

```ts value="Partial<OfferedReference>"
{
  reference: "SKI-SERVICE",
  /* … */
  supply: {
    type: "b2c_work_on_movable_goods",
    // Your Location, as /v1/locations delivers it.
    location: {
      id: "loc_munich",
      name: "Nordgrat Werkstatt München",
      address: { line1: "Sendlinger Straße 12", postalCode: "80331", city: "München", country: "DE" },
    },
  },
}
```

The marked Line is rated in the Location's country. Every other Line and the
shipping keep theirs, so one Cart can carry German and Austrian VAT. A Location
in a territory outside EU VAT, such as Büsingen, gets no Quote. With
`eu-standard`, each country is rated from its own day's import, and the Quote
expires when the first of those days ends. A Quote names the Location, so
moving the work to another Location asks the buyer again. An Offer with
`supply` ships nothing.

Goods, including work that comes with selling them, such as fitting the tyres
you sell, keep their existing goods treatment without `supply`.

The following need a tax function, not merely an Offer without `supply`:

- repairs sent in by mail and shipped back: consumer work on movable goods can
  still be taxed where the work is performed, not at the return destination;
- other services, including courses, events, food and drink, work on property
  and transport, each under its applicable place-of-supply rule;
- business buyers, under the applicable business-to-business rules.

OrbCart's own rates have no business-to-business regime: no VAT IDs, no reverse
charge, no Art. 44 place of supply. Nor do they place an ordinary consumer
service at your establishment (Art. 45). A Line without `supply` that ships
nothing is rated at the billing country, which fits electronic services such as
an e-book. If you sell to businesses or other services, use a tax function. It
receives `supply` on each marked Line and its answer stands as you send it.

## Your own tax function

Use this for a non-EU market, a tax service, or goods whose category differs
by country. OrbCart sends the
exact amounts after discounts. You return the tax for every Line and for shipping.

Nordgrat's Swiss shop charges Swiss VAT this way:

```ts title="src/swiss-vat.ts"
import type { TaxAmount, TaxContract, TaxDraft } from "@orbcart/runtime";

// Swiss rates in tenths of a percent, so the arithmetic stays in whole numbers.
const rates = new Map([
  ["standard", 81],
  ["reduced", 26],
  ["zero", 0],
]);

export const swissVat: TaxContract = (draft) => ({
  // A Line without a known rate gets no tax, so OrbCart refuses to quote it.
  lines: draft.lines.flatMap(({ id, amount, taxCategory, deposit }) => {
    const tenths = rates.get(taxCategory);
    const depositRate = deposit && rates.get(deposit.taxCategory);
    return tenths === undefined || (deposit !== undefined && depositRate === undefined)
      ? []
      : [
          {
            id,
            taxes: [vat(amount.amount, taxCategory, tenths, draft)],
            ...(deposit &&
              depositRate !== undefined && {
                deposit: [vat(deposit.amount.amount, deposit.taxCategory, depositRate, draft)],
              }),
          },
        ];
  }),
  ...(draft.shipping && {
    shipping: [vat(draft.shipping.amount.amount, "standard", 81, draft)],
  }),
});

function vat(amount: number, taxCategory: string, tenths: number, draft: TaxDraft): TaxAmount {
  const { country, currency, pricesIncludeTax } = draft;
  const tax = pricesIncludeTax
    ? Math.round((amount * tenths) / (1000 + tenths)) // included in a gross price
    : Math.round((amount * tenths) / 1000); // added to a net price

  return {
    percentage: String(tenths / 10),
    country,
    taxCategory,
    taxableAmount: { amount: pricesIncludeTax ? amount - tax : amount, currency },
    amount: { amount: tax, currency },
    rule: "ch-mwst@2024-01-01",
  };
}
```

Then set `tax: swissVat` on the Channel. The full version is
`apps/nordgrat-cart-worker/src/swiss-vat.ts`.

### What you get

`draft` contains `country`, `currency`, `pricesIncludeTax`, `shipTo`, `billTo`,
the `lines` (each with `id`, `reference`, `taxCategory`, `quantity`, `subtotal`,
`discount`, the discounted `amount` and, for
[work at your Location](#work-performed-at-your-location), `supply`) and the
selected `shipping`. `country` is the purchase's: the delivery's, the pickup's
or the billing address's.

### What OrbCart checks

When a Line has a deposit, `line.deposit` contains its own `taxCategory` and `amount`.
Return its tax lines in that answer Line's `deposit` array, separately from `taxes` for the
discounted merchandise. The same balancing rules apply to both. A missing, unexpected or
unbalanced deposit answer prevents a Quote. Deposit amounts are never discounted.

- Every Line appears by `id`, and shipping when it is charged.
- Amounts are integers in the Channel's currency.
- **Gross prices:** taxable amount plus tax equals the discounted amount.
- **Net prices:** taxable amount equals the discounted amount.

A wrong or missing answer means no Quote, never a guess. `rule` is your name for
the rule and its version. It is frozen into the Order.

[Let buyers sign in with your login →](/docs/integrate/identity)