The catalog is what you sell in one application. It has four kinds of object: products, capabilities, plans and the entitlement rules of each plan version. You edit it in the operator console under Products & Plans (the page is titled Plans & Catalog, with the tabs Plans and Capabilities), or through the Management API. Each catalog belongs to one application; two applications never share one.
How the pieces fit
A plan sells a product. Each plan has numbered versions, and a version carries the price and the entitlement rules: for each capability it grants, how much and how often the amount resets. A buyer organization subscribes to one plan version, and your code rules on capabilities by key.
Product ──── Plan ──── Plan version ──── Entitlement rule ──── Capability
(base or (primary (price, currency, (allowance, (key, type,
add-on) or add-on) interval) reset interval) overage policy)Capabilities belong to the application, not to a product, so one capability key can be granted by plans of different products.
Products
A product is what a plan sells, for example Reports. It is either a base product or an add-on product; an add-on product names the base product it belongs to.
- A product cannot be deleted while it has plans.
- A base product with add-on products cannot be deleted while they exist.
Capabilities
A capability is a key your code rules on and reports usage for, such as report_exports. It has:
| Field | What it decides |
|---|---|
key | The name your backend uses in adjudicate() and reportUsage(). Lowercase letters, digits and underscores, unique within the application |
name | The name end users see, for example in PricingTable and UsageMeter |
type | COUNT for something consumed in amounts, such as exports or tokens; BOOLEAN for a feature that is on or off |
overage_policy | What a ruling says beyond the allowance: BLOCK, ALLOW_AND_BILL or PROMPT_UPGRADE. The default is BLOCK. Each one is described in When the allowance runs out |
base_unit_price | The price of one unit beyond the allowance, before the plan version's discount. 0 means overage has no price |
Rulings treat both types the same way. A capability that the buyer organization's plan version has a rule for is granted, and its allowance counts what is used; a capability without a rule is refused with capability_not_granted. For an on-or-off feature, give the plan a rule for the capability and rule on it as a read with quantity: 0, which is allowed whatever is left of the allowance; see Read or write.
A capability cannot be deleted while a plan version has a rule for it.
Plans
A plan is a tier of a product, such as Free, Pro or Team. A plan under a base product is a primary plan; a plan under an add-on product is an add-on plan. Creating a plan also creates its first version as a draft.
| Status | Meaning |
|---|---|
DRAFT | No version has been published yet. End users do not see the plan |
ACTIVE | At least one version is published. End users see the latest published version |
ARCHIVED | No new subscriptions. Subscriptions already on one of its versions carry on |
A plan can be deleted only while none of its versions has been published; after that, archive it.
Two settings of a plan are changed through the Management API, with PATCH /mgt/v1/projects/{projectId}/plans/{planId}:
| Setting | Effect |
|---|---|
no_card_required | End users subscribe without a payment method and without Stripe, as described in Subscribe without a card. Only a plan whose versions are all priced 0 can have it; otherwise the request is refused with PLAN_PRICE_NOT_ZERO |
one_per_account | Within the application, one end-user account holds at most one subscription to this plan, across all the organizations it belongs to. A second one is refused with PLAN_ACCOUNT_LIMIT_REACHED |
Plan versions and entitlement rules
A version has the price, the currency, the billing interval (MONTHLY or YEARLY) and an overage discount, and one entitlement rule per capability it grants:
| Rule field | What it decides |
|---|---|
| Capability | Which capability the rule grants |
allowance | How much of it a subscriber may use in a period |
reset_interval | MONTHLY: the allowance starts again every month. NEVER: it is granted once |
When you publish a version, the overage price of each rule is worked out and frozen with it: the capability's base unit price times the version's overage discount (between 0 and 1, default 1), rounded to six decimal places. Changing the capability's base unit price later does not change versions already published. What happens to a version once published, and how a price change reaches subscribers, is in Plan versions.
Add-ons
Add-on products and add-on plans are part of the catalog, and the public catalog marks a plan's type as PRIMARY or ADDON. A buyer organization holds one subscription at a time, and a subscription cannot be changed to an add-on plan: the change is refused with PLAN_CHANGE_NOT_ALLOWED. PricingTable lists primary plans only.
What end users see
GET /public/v1/catalog/plans lists each ACTIVE plan of the application with its latest published version as latest_version, including the version's rules and the name of each capability. Drafts, and plans with no published version, are left out. The customer portal and PricingTable read the same list; see Checkout and self-service.