Rate tables
A rate table is a named table of values that a formula reads from. Instead of writing forty tiers or a very long expression, you put the numbers in a table and let the formula ask it a question.
Two questions, so two kinds of table.
Lookup tables
A lookup table maps a key to a value. Ask it for .de and it returns the
number stored against .de.
Code
This is what pairs with key sets: one product, one price, and the rate chosen by whichever variant is being billed.
Bracket tables
A bracket table maps ranges to values. Ask it for 18,000 and it returns the
value for the band that contains 18,000.
Code
A request for 18,000 returns 0.05. Brackets are for anything that steps by
quantity when you do not want that logic living in tiers.
When a key is missing
Every table declares what to do when the key is not there. This is required, and it is the field to think hardest about.
| Setting | Behaviour |
|---|---|
error | The lookup fails and billing stops. Loud, safe, and correct when a missing rate means a broken catalog |
zero | Returns 0. The line bills nothing |
default_value | Returns a value you supply |
The dashboard shows this as the Missing Key column, so you can see the behaviour of every table at a glance.
zero silently gives things away
A missing key under zero produces a zero-rated invoice line rather than a
failure. That is occasionally what you want and usually not. Prefer error
unless you can say why not.
Tables can also require continuous coverage, which refuses to publish a version that leaves a gap between brackets. Worth enabling on anything where a gap would silently mean a miss.
Create one in the dashboard
-
Open the catalog
Pricing Catalog in the sidebar, then the Rate Tables tab.
-
Add the table
Add Rate Table, then choose lookup or bracket, give it a slug formulas will reference, and set the missing-key behaviour.
-
Fill in the entries and publish
Rate tables are versioned. Editing entries stages a new version; publishing is what puts them in front of billing.
Create one with the API
slug, name, table_type and on_missing_key are all required, and
default_value becomes required if you choose default_value.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Type: Lookup / Bracket | table_type: "lookup" / "bracket" |
| Missing Key | on_missing_key: "error" / "zero" / "default_value" |
| Slug | slug, what a formula references |
| Status | the published version state |
| continuous coverage | requires_continuous_coverage |
Going deeper
| Topic | What it adds |
|---|---|
| Formulas | The expression that reads the table |
| Key sets | The keys a lookup table is usually keyed by |
| Costs | Values held per key rather than per band |
Reference
| Topic | When you need it |
|---|---|
| Prices | Where a formula-backed tier is attached |
| Rate tables API | Entries, versions, timeline and archive |