Tax and Tip Handling
Koard resolves tax settings hierarchically, and handles tips either at the time of sale or as a later adjustment.
Surcharge settings (
surcharge_rate,surcharge_basis,surcharge_confirmation_required) follow the same account → location → terminal hierarchy described below, but are documented on the Surcharging page.
Hierarchical tax defaults
tax_rate and tax_basis can be configured at three levels — the account, the location, and the terminal:
| Field | Meaning |
|---|---|
tax_rate |
Tax percentage. |
tax_basis |
What the tax is calculated on. |
Resolution — most specific wins. For a given transaction, Koard uses the value set on the terminal if present; otherwise it falls back to the location, then to the account. A null at a more specific level means "inherit."
Set the broad default once on the account. Only set the field on a location or terminal when it needs to differ from the level above it.
tax_rate and tax_basis here are configuration defaults (resolved from the account -> location -> terminal hierarchy). They are separate from the transaction-breakdown fields returned on a completed transaction: taxAmount (the computed tax, in cents) and taxRate (the rate actually applied to that transaction; see the transaction breakdown schema for its exact representation). Don't conflate the config input (tax_rate, a percentage) with the computed breakdown output (taxRate / taxAmount).
Tip handling
Tips are captured in one of two modes, tracked on the transaction as tip_capture_mode:
| Mode | When | Notes |
|---|---|---|
Tip at sale (tip_at_sale) |
The tip is included on the original sale. | Any non-tip-adjust transaction that carries a tip. |
Tip adjust (tip_adjust) |
The tip is added/changed after the sale (e.g. restaurant tip-on-receipt). | A dedicated tip_adjust transaction referencing the original. |
Each carries a tip_amount and tip_type (e.g. percentage or a fixed amount).
Tip adjust does not apply surcharge. A tip adjustment only changes the tip on an existing transaction — it does not recompute or add a surcharge. Surcharge is applied on the sale, independently of tips (see Surcharging).
