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 switch: switched off, it leaves the feature out of the signed license on every plan, for a feature your server enforces, while the application and your customer still see it listed as included.

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. An Enumeration feature with no options declared accepts any value and stores it unchanged. The rewrite happens when a plan, entitlement or offer is saved or imported; a copy of an existing plan, such as a new product version, and an add-on override keep the spelling they already carry.

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, grace and paid flags are in the signed license, so your application can rely on them at runtime. Display name, description and module name are sent to the application too, but unsigned, for display: use them to label a feature, not to decide whether it is licensed. Whether the value can be changed on an entitlement stays in your portal. What reaches your application lists every field and where it goes.

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 decides whether the feature reaches a license:

• Draft — not served yet. Licenses are still issued, but without the feature, and a product that links a Draft entry can’t be published. Publish the entry and it reaches every holder at their next license refresh, with nothing to re-assign.
• Preview and Published — served.
• Disabled — stop serving. Left out of licenses and can’t be newly assigned; set it back to Published to serve it again.
• Archived — never again. Left out of licenses for good.

An entitlement keeps every feature it was granted whatever the entry’s state; only the license leaves it out.

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.

A Draft or Archived entry can be deleted once nothing active refers to it: no product that is still Draft, Preview or Published carries it, no Draft or Published entitlement or offer holds its code, no plan set that isn’t archived sets a value for it, no add-on that isn’t archived grants it, and no rating campaign that is switched on asks about it. Deleting it frees its code and its place in your plan’s feature allowance. Entitlements that already carry the code keep their license exactly as it was: the feature stays left out, as it was while the entry was Draft or archived, until you define the code again.

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: its Also add to switch, which names the product and version you are looking at, is on by default and puts the entry there. 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.

New feature also asks for the entry’s Status, starting at the version’s own: a feature added to a Published version starts Published, so the product stays sellable with it in every new license. On a Draft version it starts in Draft; publish it 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.