Costs
A cost records what something costs you, so a formula can
price from it. It is the difference between typing 115.00 into a tier and
saying cost * 1.15 and letting the number follow reality.
Costs are also what makes margin reporting possible: revenue is only half of a margin.
Two scopes
Every cost is one or the other, and the dashboard filters by exactly this.
Org-scoped
An upstream fee that is the same wherever it appears: a payment provider's percentage, a carrier rate, a licence you pay per user across the whole catalog. Defined once, referenced by any formula, changed in one place.
Leave product_id off and the cost is org-scoped.
Product-scoped
A cost that belongs to one product, because it only means something there.
Shipping for a physical item, or the wholesale rate for one specific SKU. Set
product_id and the cost is owned by that product.
A product can carry several named costs, which is why they are keyed rather than being a single "cost" field.
Code
Static or calculated
A cost holds exactly one of a fixed amount or an expression.
| Kind | Field | Example |
|---|---|---|
| Static | amount | 45.00 CHF |
| Calculated | expression | primary + shipping |
An expression references other costs by key, so a composite cost stays correct
when one of its parts changes. Change shipping and every cost built on it
follows, and so does every price whose formula reads it.
Check who depends on a cost before changing it
A cost is a shared input. GET /v1/costs/{id}/consumers lists every formula and
product that reads it, which is the thing to look at before re-negotiating a
number that forty tiers are priced from.
Create one in the dashboard
-
Open the catalog
Pricing Catalog, then the Costs tab. The Org-scoped / Product-scoped / All filter is the fastest way to see which is which.
-
Add the cost
Give it a key, which is the name formulas will use, and either a value or an expression. Write a description; six months later
primarywill not be self-explanatory. -
Price from it
In a formula, reference the key:
cost * 1.15, orprimary + shippingfor a composite.
Create one with the API
Only key is required, and you must set exactly one of amount or
expression. Sending both, or neither, is rejected.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Cost Key | key, what formulas reference |
| PRODUCT column | product_id; empty means org-scoped |
| Org-scoped filter | costs with no product_id |
| Value | amount, a Money value |
| a calculated cost | expression, referencing other keys |
| what depends on it | GET /costs/{id}/consumers |
Going deeper
| Topic | What it adds |
|---|---|
| Formulas | The expressions that read these values |
| Pricing models | How the resulting rates apply across tiers |
| Analytics | Margin, which needs cost as well as revenue |
Reference
| Topic | When you need it |
|---|---|
| Products | Product-scoped costs on the product itself |
| Costs API | Every field, plus consumers and archive |