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 setting | Use it when | Who calculates |
|---|---|---|
tax: "eu-standard" | You sell standard-rated goods to EU countries. | OrbCart, with the EU's daily national standard rates. |
tax: yourFunction | Reduced rates, non-EU markets, or your ERP or tax service decides. | You return complete amounts. |
| no setting | Legacy only. A small built-in table, not EU-wide coverage. | OrbCart, for that table only. |
EU standard VAT
Opt in on the Channel
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
"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 testAdd --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 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:
| 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 |
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:
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.