# 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

```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] },
},
```

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

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

```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],
]);

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 →](/integrations/identity)