Plans

Named tiers that bundle entitlements for customers.

Every customer is on exactly one plan. Plans define what credits customers can consume, at what limits, and which topups are available or automatically included.

---

Schema

plans:
  <plan-id>:
    label:        string         # Human-facing name. Default: ''.
    period:       string         # 'monthly' | 'yearly' | 'weekly' | 'daily'. Default: 'monthly'.
    subscription: string         # Subscription entitlement name. Default: 'subscription'.
    trial_period: float | string # Optional trial period (e.g. '14days').
    default:      bool           # Is this the default plan? Default: false.
    hidden:       bool           # Hide from public plan listings. Default: false.
    entitlements:                # Map of entitlement ID → Entitlement.
      <entitlement-id>: {}
    topups:                      # Map of topup ID → Topup.
      <topup-id>: {}

---

Fields

label

Human-facing name for this plan. Available in customer state and policy serialization for display in pricing UI.

period

The billing period for this plan.

Value	Duration
monthly	30 days. Default.
yearly	365 days
weekly	7 days
daily	1 day

The period affects how marginSnapshot() scales usage for projections. It does not control meter resets — those are defined per-entitlement via limit.reset_inc.

subscription

The name of the entitlement used to track plan subscription. Defaults to 'subscription'. When ensureCustomerPlanQuantity() is called, Limitr increments this entitlement if the customer's meter is below 1 — useful for triggering a billing charge at plan activation.

To charge for a plan subscription, define a soft-limit entitlement with a limit of 0 so the first increment fires a meter-overage event:

entitlements:
  subscription:
    limit:
      credit: plan_fee
      mode: soft
      value: 0

trial_period

Optional. A Stof duration string (e.g. '14days', '30days'). When set, ensureCustomerPlanQuantity() will not increment the subscription entitlement until the trial period has elapsed since the customer was created.

trial_period: 14days

default

If true, this plan is used when createCustomer() is called without a plan argument. Only one plan should have default: true.

hidden

If true, this plan is excluded from public plan serialization. Useful for internal or legacy plans.

entitlements

A map of entitlement IDs to Entitlement objects. See Entitlements for the full schema.

topups

A map of topup IDs to Topup objects. Topups can be applied manually with applyCustomerTopup() or included automatically for all customers on the plan. See Topups & Grants for the full schema.

---

Example

plans:
  starter:
    label: Starter
    period: monthly
    default: true
    entitlements:
      chat_access:
        description: Access to AI chat
      chat_input:
        limit:
          credit: sonnet_input
          mode: hard
          value: 500000
          resets: true
          reset_inc: 1day
      chat_output:
        limit:
          credit: sonnet_output
          mode: hard
          value: 200000
          resets: true
          reset_inc: 1day

  growth:
    label: Growth
    period: monthly
    entitlements:
      chat_access:
        description: Access to AI chat
      chat_input:
        limit:
          credit: sonnet_input
          mode: soft
          value: 700000
          resets: true
          reset_inc: 1day
      chat_output:
        limit:
          credit: sonnet_output
          mode: soft
          value: 400000
          resets: true
          reset_inc: 1day
    topups:
      ai_credit_pack:
        description: 10 AI credits
        credit: ai_credit
        value: 10
        price:
          amount: 12.50

---

SDK

policy.plan()

Returns the plan record for a plan ID or customer ID. Falls back to the default plan if def is true (default) and the specified plan isn't found.

const plan = await policy.plan('growth');
const customerPlan = await policy.plan('user_123'); // looks up customer's plan

policy.defaultPlan()

Returns the plan marked default: true, if one exists.

const plan = await policy.defaultPlan();

policy.setPlan()

Adds or replaces a plan in the policy by ID. planStof is a Stof string defining the plan. Fires a plan-set event.

await policy.setPlan('enterprise', planStofString);

policy.deletePlan()

Removes a plan by ID. Fires a plan-removed event. Returns true if removed.

await policy.deletePlan('legacy');

policy.planPeriod()

Returns the period string for a plan.

const period = await policy.planPeriod('growth'); // 'monthly'

policy.planTrialPeriod()

Returns the trial period in milliseconds, or null if no trial is defined.

const trialMs = await policy.planTrialPeriod('starter'); // null or ms value

policy.planSubEntitlementName()

Returns the subscription entitlement name for a plan.

const name = await policy.planSubEntitlementName('growth'); // 'subscription'

policy.setCustomerPlan()

Changes a customer's plan. When overwrite_meters is true (default), resets the customer's meters. Returns true if the plan changed, and fires customer-set and customer-plan-changed events.

await policy.setCustomerPlan('user_123', 'growth');