Features from Stripe Entitlements
Manage features in Stripe's Product catalog instead of the config: lookup keys cached from the webhook, never fetched per check.
By default a plan's features are its features list in billing.config.ts. To manage them in Stripe instead (Product catalog → Features, attached to products), switch the source:
export const billingConfig = defineBillingConfig({ entitlements: 'stripe', // optional: the lookup keys you expect, so hasFeature('…') is typed entitlementKeys: ['export', 'sso'], // plans have no `features` in this mode // ...});- A feature's lookup key is what
hasFeature('export')andrequireFeature('export')check. defaultFeaturesstill apply to every account.- Plan
featuresare refused in this mode, so there's one source. - Limits stay in the config.
entitlementKeyswithoutentitlements: 'stripe'is a config error.
How It Stays Fast
The kit never calls Stripe on a check. Stripe sends entitlements.active_entitlement_summary.updated when a customer's features change; the lifecycle job fetches the customer's active entitlements and stores their lookup keys on the customer's subscription rows. getBilling reads that cache like any other column. A new subscription gets its keys when its row is first synced.
- Add the event to your webhook (it's in the list in Setup and Go Live).
- Keys are per Stripe customer: every active subscription of the customer counts. The kit uses one customer per organization or user.
- A key Stripe sends that isn't in
entitlementKeysis still applied and logged as a warning, so you notice a missing declaration. - If Stripe can't find the customer, the cached keys are kept and a warning is logged.
Testing
fakeBilling({ config: billingConfig, features: ['export'] }) takes the lookup keys as features. On the test database, seedSubscription({ db, table: subscription, referenceId, plan: 'pro-monthly', entitlementKeys: ['export'] }) writes a row as if synced.