Key sets
A key set lets one product sell many variants without becoming many products.
A domain registrar sells hundreds of TLDs. A cloud sells dozens of instance types across regions. Modelled naively that is one product per variant, each with its own prices, all needing the same edit whenever anything changes. A key set collapses that into one product, many keys.
How it fits together
Three pieces, in order.
The set holds the keys
A key set is an organisation-wide registry: a name, a slug, and its entries.
zz-tlds might hold .com, .de, .io. Nothing is priced yet; this is the
vocabulary.
A product links to the set
Give a product a key_set_id and it becomes keyed. Its prices may now carry
a price_key, and the allowed values are exactly the set's entries.
A product can subtract from that list but never add to it: key_set_excluded_keys
removes keys this particular product does not sell. Adding a key nobody defined
would be a typo, so it is rejected.
Prices carry the key
Each price covers one price_key, or one price marked as the set
price covers all of them. Usage events for a keyed product must name their
price_key; events for an ordinary product must not.
Code
Pair it with a lookup table when the list is long
Three keys are fine as three prices. Three hundred are not. Put the rates in a lookup rate table keyed by the same keys, and let one formula-backed price serve every variant.
Create one in the dashboard
-
Open the catalog
Pricing Catalog, then the Key sets tab.
-
Create the set
New key set, give it a name and a slug, and seed the keys you already know. The list shows how many keys each set holds and how many products use it.
-
Link a product to it
On the product, choose the key set. It is immutable once the product has a price or a subscription item, so pick it before you start pricing.
Create one with the API
slug and name are required; entries seeds the set in the same call.
GET /v1/key-sets/{id}/references lists what depends on it before you change
anything.
Dashboard and API names
| In the dashboard | In the API |
|---|---|
| Keys count | entries[] on the set |
| Products count | GET /key-sets/{id}/references |
| Slug | slug, org-unique |
| the product's key set | key_set_id on the product |
| keys this product does not sell | key_set_excluded_keys |
| the variant on a price | price_key |
Going deeper
| Topic | What it adds |
|---|---|
| Rate tables | One price for hundreds of keys, rates looked up |
| Products | Where a product is linked to a set, and why it is immutable |
| Usage | Why a keyed product's events must carry price_key |
Reference
| Topic | When you need it |
|---|---|
| Prices | Per-key prices and the set price |
| Key sets API | Entries, references and archive |