Features & the feature catalog

A feature is a capability you switch on, gate, or meter — “API access”, “seats”, “export to PDF”. Each has a dotted feature code (e.g. api-calls.total, role-based.permissions) and a data type:

Boolean · Numeric · Text · Enumeration · Metered · JsonField

The data type matters for booleans: a Boolean feature’s value is the grant itself. A plan that sets it to "true" includes the feature; "false" excludes it, and the license says so explicitly — the feature stays visible to the application as locked, and the SDK’s IsValidFeature answers false. A feature missing from a license altogether is different from an excluded one: missing usually means the license predates the feature, and your application decides the default.

A plan can withhold a feature of any type in two ways: Denied puts the feature in the license explicitly deactivated; the application can still show it, IsValidFeature answers false, and attempts count as denied checks — use it for plan gating you want customers to see. Not included leaves the feature out of the license entirely, indistinguishable from a license that predates it — use it to hide a capability from a plan. An add-on that carries the feature overrides both. Both are separate from the product-level “in license” flag, which keeps a server-side feature out of every license on every plan.

An Enumeration feature lists the values it allows. A plan or entitlement may spell one of them in any case — Gold is accepted against a declared gold — but what gets stored, and what your application reads out of the license, is always the spelling in the catalog. That is why two options that differ only by case are refused: with both Gold and gold declared, nothing could say which one a value meant.

A feature can be marked Public or Internal, can be made available during trial or grace periods, and can be flagged so an entitlement may override its value later.

What reaches the license, and what does not

Only some of what you fill in travels to the customer’s application. Feature code, value, and the trial and grace availability flags are in the license — your application reads them at runtime. Display name, description and the value-editable-on-entitlement flag are administrative: they organize the back office, not the license.

Feature codes are permanent and unique across your whole catalog, so name a feature after what it does rather than what it is called this quarter. The same code carries across every version of a product, which is what lets a customer move between versions without their application having to know.

Trials: granting vs. withholding

Two flags control how a feature behaves during a trial, and they are not opposites.

Flag	Effect
Available during trial period	Grants. Lets a feature that is otherwise switched off be used while the customer is trialling.
Paid feature	Withholds. Keeps a feature out of the license while the customer is trialling, even if it is enabled.

The distinction matters because availability is an or: a feature is usable if it is enabled or if it is trial-available. So enabling a feature already makes it usable during a trial — “available during trial period” cannot take that away. Paid feature is the flag that can.

Mark a feature as Paid when it represents functionality a trial should not include. It defaults off, so existing features are unaffected.

The restriction is evaluated each time a license token is issued, not frozen when the customer activates. It therefore lifts on its own once they are no longer trialling — no re-activation, and nothing for you to switch back.

A feature granted only through an add-on is never withheld this way: an add-on carries no paid marker, and add-ons are only ever allowed to widen access. To withhold it during trials, mark it Paid on the product.

The feature catalog

The feature catalog is where a product’s features are defined — the single source of truth for “what features exist, and what each one means.” It’s scoped to a product family, so every version of a product shares the same definitions, and feature codes must be globally unique across all non-archived products.

Entries carry a state — Draft, Preview, Published, Disabled, Archived — and each state gates something: a Draft entry blocks publication of any product that links it, while Disabled and Archived entries can’t be newly assigned and are suppressed from issued licenses.

You can move an entry to any state at any time, in either direction — that’s how you take a published definition back to Draft to edit it. Archived is the only exception: an archived entry can never be brought back. Products follow the same rule.

Once one live entitlement carries a feature’s code, its published definition is locked: edits to the name, units, metric, type, visibility or enum options are refused. Only the value weight — how much the feature counts in value-delivered analytics — stays editable. Get the definition right before it ships.

Everything else references features by code: a product carries feature instances, a plan assigns values and tiers to those codes, and an entitlement is granted a snapshot of them. Defining a feature once, in the catalog, keeps that code meaning the same wherever it’s used.

Product features vs. catalog entries

• A catalog entry is the definition (code, type, visibility, lifecycle).
• A product feature is that feature as it appears on a specific product version, with its value — what the product offers.

Most features want both, so New feature creates both: Add to this version is on by default and puts the entry on the version you are looking at. Turn it off when a family has several versions and the new feature belongs to one you are not on; add it later from Features in this version → Add features. The switch is off and unavailable on a locked version, which accepts no changes at all.

The lifecycle is the same either way — the entry starts in Draft, and a product version carrying a Draft feature cannot be published. Publish the entry once its definition is settled.

How it relates

• Defined in → the catalog, per product family.
• Valued by → plans, which set each feature’s value and tiers.
• Snapshotted into → entitlements at grant time.