Freemium to Enterprise

This guide walks through setting up a classic three-tier packaging model: a Free plan for onboarding, a Pro plan for self-serve, and an Enterprise plan that routes to sales for custom quotes. It covers feature packaging, trials, pricing tables, and how to apply custom enterprise pricing per-customer.

What you’ll set up:

Free plan (no payment required)
Pro plan (monthly/yearly, optional usage/credits)
Enterprise plan (contact sales redirect)
Optional trials that auto-convert to paid
Per-customer enterprise pricing using price overrides

Important notes:

Prepaid top-up credit packs are not supported yet.
Trials are modeled as dedicated trial plans linked to a parent plan.

1) Define your three plans

Free plan (Freemium):

Create a plan with $0 fixed pricing and no billed usage components. Free plan detection is automatic when all components are $0 (and usage unit costs are $0).
Add boolean/numeric features you want available on the free tier. For small allowances, create usage credits (plan-scoped, renew on billing) so you can gate usage without charging.

Pro plan:

Add fixed monthly/yearly pricing. Optionally add usage components (per-unit) and attach usage credits for included quotas. Credits auto-grant on subscribe and renew on billing.

Enterprise plan:

Create a placeholder plan (e.g., "Enterprise") to represent this tier. The key is how it's configured in the Pricing Table, not its specific pricing components, since those will be custom per-customer.

2) Add features and (optional) usage credits

Boolean features (toggles) are added to plans; they’re checked via entitlements in your app.
Usage credits (plan-scoped) define included quotas per cycle. They are granted on subscription creation and applied as negative line items at billing when billingVisible is true. Overages are billed at the usage component’s unit price.

Example (usage credits for Pro plan):

curl -X POST "https://api.getlumen.dev/v1/credits/definitions" \
  -H "Authorization: Bearer $LUMEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "plan",
    "applicationType": "usage",
    "planId": "plan_pro",
    "priceId": "price_pro_monthly",
    "priceComponentId": "comp_usage_api",
    "name": "Included API Quota",
    "defaultAmount": 10000,
    "refillAmount": 10000,
    "renewOnBilling": true,
    "billingVisible": true
  }'

3) Configure your Pricing Table (public)

Create or edit your Pricing Table and add the three plans in the order you want. Mark Pro as “Popular” if desired.
For the Enterprise row, enable the enterprise toggle and set an enterpriseRedirectUrl (e.g., your contact form). The public Pricing Table response includes isEnterprisePlan and enterpriseRedirectUrl, so the button becomes “Contact sales” instead of starting checkout.
The table automatically detects monthly/yearly amounts from your prices’ components. Seat-based intervals display as “month per seat”.

Notes:

The public Pricing Table requires your publishable key.
Trial information for a parent plan is included automatically when a linked trial plan exists (see next section).

4) Optional: Add a trial that auto-converts

Trials are separate plans linked to a parent plan with trialParentPlanId and trialDays. The Pricing Table will show trial availability for the parent plan. During trial setup, a scheduled change is created to migrate to the parent plan at trial end.

Behavior:

Trial credits (if any) are separate from paid plan credits.
At trial end, the subscription migrates to the parent plan/price automatically via a scheduled change.

5) Gate features in your app

Use entitlements for both boolean and numeric features.

import { isFeatureEntitled } from "@getlumen/server";

const allowed = await isFeatureEntitled({
  userId: currentUserId,      // or lumenCustomerId
  feature: "advanced-reports" // slug from your plan features
});

if (!allowed) {
  // Hide/disable feature or prompt upgrade
}

For usage-based features, send events from your server so billing can compute period usage and apply credits/overage.

import { sendEvent } from "@getlumen/server";

await sendEvent({ name: "api-calls", value: 1, userId: currentUserId });

Note: The feature slug you gate (e.g., api-calls) must exist on the plan. When you add a usage feature in the plan UI, it links to the metric; otherwise create the feature before gating.

6) Enterprise quotes with custom per-customer pricing

When a lead clicks “Contact sales” on the Enterprise row, handle the form offsite. After agreement:

Create a negotiated Price for the Enterprise plan (monthly/yearly as needed).
Apply it to the customer’s existing subscription using a price override (creates a new version of the subscription with the target price).

POST /v1/subscriptions/price-override/:stableSubscriptionId
Content-Type: application/json

{ "priceId": "price_enterprise_custom" }

Behavior:

The override takes effect immediately (new subscription version). For future-dated migrations (e.g., at next billing), use scheduled changes (plan migrations) mechanisms instead.

7) What happens at billing

Fixed and per-seat components are billed per their recurrence rules (with proration for mid-cycle seat adds when configured to bill immediately).
Usage components compute quantity from events during the billing window.
Usage credits (billing-visible) show as negative line items; overage is charged for any remainder.
Monetary credits (discounts) apply after charges via the credit waterfall.

References

Pricing Tables (public): publishable-key based; supports Popular badge and Enterprise redirect
Trials: trial plans linked to parent plans; scheduled change at trial end
Price override API: POST /v1/subscriptions/price-override/:id
Credits: definitions/grants; usage vs monetary; renew on billing
Entitlements: isFeatureEntitled(); usage-aware with creditInfo when using the API

Freemium to Enterprise

On this page