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 with the API
slug and name are required; entries seeds the set in the same call. Add or
change keys later with PUT /v1/key-sets/{id}/entries, which upserts by key;
retire a key by upserting it with "status": "retired".
GET /v1/key-sets/{id}/references lists what depends on it before you change
anything.
Link a product to the set with key_set_id on POST /v1/products or
PATCH /v1/products/{id}. The link is immutable once the product has a price or
a subscription item, so set it before you start pricing.
Terms and API names
| Term | In the API |
|---|---|
| the keys in a set | entries[] on the set |
| the products that use a set | GET /key-sets/{id}/references |
| the set's short name | 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 |