FAQ
Frequently asked questions about Lumen
General
What is Lumen and when should I use it instead of Stripe Billing?
Lumen is a B2B billing engine optimized for complex SaaS pricing and feature-based entitlements. It provides:
- Append-only plan/versioning for safe changes over time
- A flexible Price DSL with multiple components (fixed, per_unit, usage, etc.)
- First-class features/entitlements with override precedence
- Credits (usage and monetary) integrated with billing and entitlements
- Multi-PSP support (Stripe primary, Dodo) and webhook-driven reliability See also: /docs/getting-started/lumen-vs-stripe.
Which payment providers are supported and how do I connect them?
- Stripe (primary) and Dodo Payments are supported today.
- Connect in Developer Settings by adding API keys. For Stripe, Lumen auto-creates a webhook endpoint targeting
POST /v1/public/webhook/:merchant_id; for Dodo,POST /v1/public/webhook-dodo/:merchant_id. - Stripe webhooks listen for:
payment_intent.succeeded,payment_intent.payment_failed,setup_intent.succeeded,setup_intent.setup_failed,checkout.session.completed. See: /docs/api-reference/stripe-api.
How does tax work today (B2B vs B2C)? What should I configure first?
- Scope is B2B-focused. If a customer lacks business identifiers (no
taxIdand nobusinessName), we treat it as B2C and apply 0% tax with reason codeb2c_tax_not_supportedon the invoice. - Configure tax via the onboarding wizard: choose Automatic, a single default rate, or advanced manual rates; US nexus configuration is supported. See: /docs/api-reference/tax-api.
What security model and API key types does Lumen use?
- Two key types: secret (
sk_...) and publishable (pk_...). Secret keys are stored hashed/encrypted; publishable keys are plaintext to enable public use. - When listing API keys, only key prefixes are returned; publishable keys can be retrieved once for client use. See: /docs/api-reference/api-keys-api.
Getting started
What’s the fastest path to my first live subscription?
- Create a plan, features, and prices (monthly/yearly) in the dashboard
- Connect Stripe or Dodo (Developer → Payment Provider)
- Create a Pricing Table and embed it using your publishable key via the
X-Lumen-Keyheader - For paid plans, customers complete checkout; for free plans, subscriptions are created immediately Alternatively, create subscriptions via API. See: /docs/features/ui-components/pricing-table, /docs/api-reference/pricing-tables-api, /docs/guides/manual-plans-pricing.
How do trials and free plans work?
- Trials use dedicated trial plans (
isTrialPlan,trialParentPlanId,trialDays). Pricing Tables expose trial details for parent plans. - Free plans are auto-detected ($0 with no billable usage components) and don’t require a payment method; a free subscription is created and invoiced for $0.
Can I price in multiple currencies?
Yes. Create multiple prices for the same plan with different currency values. The latest price per currency is used for display and billing.
Plans & features
How do plans, plan versions, and prices work together?
Lumen uses an append-only model: new plan versions are created instead of mutating existing ones. Existing subscriptions stay on their current version until migrated. A plan can have multiple prices with componentized billing logic (fixed, per_unit, usage) and discounts/time rules.
See: /docs/features/plans-pricing and /docs/features/advanced-pricing.
How do features and entitlements work, and how do overrides take precedence?
Feature types are boolean, number, or string. Precedence: Subscription override → Plan feature → Feature default. Entitlement checks combine plan/override state with credit allowances and usage where relevant. See: /docs/features/entitlements.
Billing & payments
How are billing cycles scheduled and handled across timezones?
Each price component includes a recurrence_rule (iCal RRULE). We honor TZID intent, handle DST and month-end dates (29–31), and store all timestamps in UTC.
How does proration work for mid‑cycle plan/price or seat changes?
We prorate based on time remaining in the billing period using daily-rate calculations (old vs new amounts). Proration can be applied immediately (separate invoice) or on the next cycle. Seat additions are charged mid-cycle with proration; seat removals validate against usage history.
What happens on payment failure, and how does payment‑method failover work?
For subscription charges, we first use the subscription’s configured payment method. If that fails, we automatically try the customer’s next available payment method (excluding previously attempted ones) on subsequent failure webhooks, before entering dunning.
How are invoices generated and paid? Can I retry or send a payment link?
Invoices are generated by a jobs pipeline from price components (fixed, usage, seats) with detailed line items and PDFs. Payments run automatically when enabled; for unpaid invoices you can:
- Retry programmatically:
POST /v1/invoices/:id/retry-payment - Send a hosted payment link (Stripe Checkout or Dodo payment link) when no method is on file See: /docs/api-reference/invoices-api and /docs/api-reference/payments-api.
Usage & entitlements
How do I track usage events and define metrics for usage‑based billing?
Send events via POST /v1/events (or /v1/events/batch) with an idempotencyKey. Events are stored in QuestDB (with Postgres backup). Metrics can be simple (count/sum/avg) or SQL-based and are used during billing and entitlement checks. See: /docs/api-reference/events-api.
How do I check entitlements in my app?
Use the Entitlements API:
- Get all for a customer:
GET /v1/entitlements/:customerId?isExtCustId=true|false - Check one feature:
GET /v1/entitlements/:customerId/feature/:featureSlug?isExtCustId=true|false - Batch check:
POST /v1/entitlements/:customerId/featuresResponses includeentitled,source(plan/override/credits), and credit/usage context. See: /docs/api-reference/entitlements-api.
What are credits and how are they applied?
- Types: usage credits (feature allowances) and monetary credits (invoice discounts)
- Scopes: component-level, price-level, plan-level, and merchant-level
- Behavior: hourly expiration processing; renewals on billing or RRULE schedule; detailed audit via credit transactions Credits apply during invoice generation and power entitlements for numeric features. See: /docs/features/credits and /docs/api-reference/credits-api.
Public pricing
How can I publish and embed pricing tables safely?
Use your publishable key via the X-Lumen-Key header to fetch public pricing tables by slug. Lumen validates plan membership and returns a structured object for rendering, including trial info and credit allowances per feature.
See: /docs/features/ui-components/pricing-table and /docs/api-reference/pricing-tables-api.
Support
How do I get help?
- Documentation: Start here for common questions
- Email: founders@getlumen.dev
- Community: Join our Discord for peer support