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') and requireFeature('export') check.
  • defaultFeatures still apply to every account.
  • Plan features are refused in this mode, so there's one source.
  • Limits stay in the config.
  • entitlementKeys without entitlements: '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 entitlementKeys is 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.