Connect your systems

ORBCART 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 reduced rate from a product name, 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 standard-rated goods to EU countries.OrbCart, with the EU's daily national standard rates.
tax: yourFunctionReduced rates, non-EU markets, or your ERP or tax service decides.You return complete amounts.
no settingLegacy only. A small built-in table, not EU-wide coverage.OrbCart, for that table 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] },
},

Only Offers with taxCategory: "standard" can be quoted. Don't use this mode for books, food or other reduced-rate goods.

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 standard rate. 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

Your own tax function

Use this for reduced rates, a non-EU market, or a tax service. 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],
]);

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 }) => {
    const tenths = rates.get(taxCategory);
    return tenths === undefined
      ? []
      : [{ id, taxes: [vat(amount.amount, taxCategory, tenths, 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 examples/nordgrat/src/swiss-vat.ts.

What you get

draft contains country, currency, pricesIncludeTax, shipTo, billTo, the lines (each with id, reference, taxCategory, quantity, subtotal, discount and the discounted amount) and the selected shipping.

What OrbCart checks

  • 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