Skip to Content
Integrate

ORBCOMMERCE DOCUMENTATION

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 settingUse it whenWho calculates
tax: "eu-standard"You sell to EU countries.OrbCart, with the EU's daily national rates.
tax: yourFunctionNon-EU markets, or your ERP or tax service decides.You return complete amounts.
no settingYou 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:

CategoryRate
standardThe national standard rate.
reducedThe lower reduced rate, at least 5 %.
intermediateThe higher of two reduced rates.
super_reducedThe rate below 5 %.
zero0 %, with the right to deduct input VAT.
exempt0 %, 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.

Countrystandardreducedintermediatesuper_reduced
AT2010134.9
BE21612
BG209
CY19593
CZ2112
DE197
DK25252525
EE24913
ES21104
FI25.51013.5
FR205.5102.1
GR246134
HR25513
HU27518
IE23913.5
IT225104
LT21512
LU178143
LV21512
MT1857
NL219
PL2358
PT23613
RO2111
SE25612
SI2259.5
SK23519

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

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

Every tax category is quoted at the day's national rate.

Add the Cron trigger

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:

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

stateMeaning
readyToday's import completed.
waitingToday's rates are there. The next import is not due yet.
retryingThe import failed and will try again (after 15, 30, 60, 120 min).
exhaustedToday'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:

CountryExcluded
DEHeligoland, Büsingen
ATJungholz, Mittelberg
ESCanary Islands, Ceuta, Melilla
FROverseas departments and collectivities (postal codes 97, 984 to 989). Monaco counts as France.
ITLivigno, Campione d'Italia
PTMadeira, Azores
FIÅland
GRMount Athos
CYKyrenia 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.

{
  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:

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, 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 →

On this page