Copy page

Pricing in depth

Price formulas

A formula lets a tier compute its rate instead of stating it. Where a normal tier says 109.00, a formula says cost.ek * 1.15 and works the number out at billing time.

Reach for one when the rate depends on something that moves: an upstream cost you re-negotiate, a rate you look up in a rate table, or a margin you want to change in one place rather than across forty tiers.

✕

What an expression is

An expression is arithmetic over named values: + - * / %, comparisons, and the functions if, min, max, round, ceil, floor, abs, lookup(SLUG, key) and bracket(value, SLUG) (the last two read a rate table). Numbers are exact decimals, never floating point. Two kinds of name appear in it.

Costs, by key

cost.ek * 1.15 reads the cost with the key ek and adds 15%. If your upstream price is CHF 100, the tier charges CHF 115. Re-negotiate to CHF 92 and every tier using this formula follows, with no price edits. A formula reads a cost only in the currency of the price it computes.

Variables, with defaults

margin is a variable the formula declares, with a default you can override per tier. One formula, cost.ek * margin, then serves every tier:

Code
formula     cost.ek * margin         default margin = 1.15

tier 1      margin 1.30   ->  cost 100  =  CHF 130.00
tier 2      (default)     ->  cost 100  =  CHF 115.00
tier 3      margin 1.05   ->  cost 100  =  CHF 105.00

That is the point of variables. The shape of the calculation is written once; each tier supplies only the number that differs.

Create one in the dashboard

Over the API, this is POST /v1/price-formulas; see Create one with the API.

Create one with the API

name and expression are required; each variable needs a name and a type (number, string or boolean). A default is a plain number, never a money amount.

Formulas are versioned. A new formula is a draft until it is first published, and later edits stage on its working draft (PUT /v1/price-formulas/{id}/draft/content, discarded with DELETE /v1/price-formulas/{id}/draft) instead of repricing anything live. Publish with POST /v1/changes, operation catalog.publish_version and subject_kind: "price_formula", now or at a set time; see Versioning. Before you do, GET /v1/price-formulas/{id}/versions/{version}/referrers shows what uses the formula. A tier records the formula version in force when its product publishes, so a pinned subscription keeps billing that version.

Dashboard and API names

In the dashboard	In the API
Expression	expression
Variables	variables[], each a name, a type and an optional default
a tier's FORMULA column	tiers[].formula_id
per-tier override	tiers[].formula_defaults
Custom / System filter	formulas you wrote, versus built-in ones

Going deeper

Topic	What it adds
Costs	The values an expression reads by key
Rate tables	Looking a rate up rather than calculating it
Pricing models	How the resulting rates are applied across tiers

Reference

Topic	When you need it
Prices	Where a formula is attached to a tier
Price formulas API	Every field, plus versions and referrers