Recurring-billing engine selection and operation for SaaS — picking and running a subscription/usage-billing platform (Chargebee, Recurly, Maxio, Zuora, Stripe Billing, Orb, Lago, Zoho Billing) on top of your own payment gateway, where you stay seller of record. Use when choosing a billing engine, deciding whether to build billing on Stripe Billing vs a dedicated tool, adding usage-based / metered / hybrid pricing, automating dunning and failed-payment retries, getting proration right on mid-cycle upgrades/downgrades, needing revenue recognition (ASC 606 / IFRS 15), weighing open-source self-hosted billing (Lago) vs SaaS, or planning a billing-platform migration. Do NOT use for Chargebee-specific API/config (use /sales-chargebee), Merchant-of-Record vs self-managed tax — who remits VAT/GST (use /sales-merchant-of-record), checkout-conversion optimization (use /sales-checkout), or churn/retention strategy beyond billing mechanics (use /sales-membership).
Instrucciones de origen · Vista previa de solo lectura
name
sales-subscription-billing
description
Recurring-billing engine selection and operation for SaaS — picking and running a subscription/usage-billing platform (Chargebee, Recurly, Maxio, Zuora, Stripe Billing, Orb, Lago, Zoho Billing) on top of your own payment gateway, where you stay seller of record. Use when choosing a billing engine, deciding whether to build billing on Stripe Billing vs a dedicated tool, adding usage-based / metered / hybrid pricing, automating dunning and failed-payment retries, getting proration right on mid-cycle upgrades/downgrades, needing revenue recognition (ASC 606 / IFRS 15), weighing open-source self-hosted billing (Lago) vs SaaS, or planning a billing-platform migration. Do NOT use for Chargebee-specific API/config (use /sales-chargebee), Merchant-of-Record vs self-managed tax — who remits VAT/GST (use /sales-merchant-of-record), checkout-conversion optimization (use /sales-checkout), or churn/retention strategy beyond billing mechanics (use /sales-membership).
argument-hint
[describe your billing decision — e.g., 'usage-based billing engine for B2B SaaS' or 'Stripe Billing vs Chargebee']
Helps choose and operate a recurring-billing engine — the system that turns subscriptions and usage
into invoices, retries failed payments (dunning), handles proration, and (optionally) does revenue
recognition — running on top of your own payment gateway so you stay the seller of record. This is
a different decision from a Merchant of Record (who absorbs global tax liability — see
/sales-merchant-of-record).
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated knowledge.
Ask the user (lead with a best-effort answer if they've already told you most of this):
What's the decision?
A) Which billing engine — Chargebee vs Recurly vs Maxio vs Zuora vs Stripe Billing vs Orb vs Lago
B) Build on Stripe Billing vs adopt a dedicated engine
C) Add usage-based / metered / hybrid pricing to existing billing
D) Migrate off / onto a billing platform
E) An operational need — dunning, proration, or revenue recognition (ASC 606)
Pricing model? Flat-rate subscriptions · per-seat · usage/metered · credits/prepaid · hybrid
(subscription + overage). Usage-heavy products narrow the field hard (Orb/Metronome/Lago/Maxio).
Stage / team? Solo/indie · small team (no RevOps/finance) · scaling B2B with finance ops ·
enterprise needing a GAAP system of record.
Constraints? Already on Stripe for payments? · need open-source / data ownership / self-host? ·
need RevRec or ERP/accounting sync? · budget sensitivity.
Seller-of-record or Merchant-of-Record? If you want someone else to remit global VAT/GST/sales
tax, that's a MoR decision — route to /sales-merchant-of-record. Billing engines here leave tax to you.
Skip-ahead rule: if the prompt already provides most of this, go straight to Step 4 with stated
assumptions, then ask 1–2 critical clarifiers.
Connecting the billing engine to a CRM/warehouse/other tools (iPaaS)
/sales-integration {question}
When routing, give the exact command, e.g. "This is Chargebee-specific setup — run: /sales-chargebee how do I verify webhooks".
Step 3 — Engine comparison reference
Read references/platforms.md for the full comparison — the per-engine matrix (Chargebee, Recurly,
Maxio, Zuora, Stripe Billing, Orb, Lago, Zoho Billing), how each handles usage vs subscriptions, dunning,
proration, RevRec, pricing model, and migration cost. Also lists adjacent metering tools (Metronome).
Answer using only the relevant section. Don't dump the whole reference.
Step 4 — Actionable guidance
The core decision: Stripe Billing vs a dedicated engine
Already on Stripe, simple flat/per-seat subscriptions, small team → Stripe Billing. Cheapest
(~0.7% of billed volume), zero extra integration, fine until pricing gets complex. It lacks deep dunning
analytics, RevRec, and flexible catalog modeling.
Complex catalog, hybrid/usage pricing, want the full revenue lifecycle automated → dedicated engine
(Chargebee/Recurly/Maxio). They orchestrate your gateway (often Stripe) — you keep the processor and
add billing depth on top.
Pick by what dominates your model
Subscription-first, growing SaaS adding usage overages, want the whole lifecycle → Chargebee. Broadest
feature set; UI/setup are involved (route setup to /sales-chargebee).
High-volume subs where reducing churn / collecting variable invoices is the priority → Recurly. Dunning
and revenue-recovery focus; from ~$149/mo + fees.
B2B SaaS that must tie usage billing to RevOps + RevRec reporting → Maxio (ex-Chargify + SaaSOptics).
Enterprise needing a GAAP-compliant global system of record → Zuora. Most powerful, heaviest.
Usage metering IS the product, stack already built → Orb (or Metronome) — accurate event metering first.
Want open-source control, no revenue tax, comfortable owning hosting/eng → Lago (self-host or cloud).
SMB already in the Zoho suite → Zoho Billing — cheapest, tightly integrated, lighter on advanced needs.
Operational realities
Dunning beats discounting. Most "churn" on these platforms is involuntary (failed cards). Smart,
decline-type-aware retries + card-expiry reminders recover real revenue — turn them on before chasing offers.
Proration is where surprises hide. Mid-cycle changes issue credits whose type/timing depends on
invoice state — preview with the estimate API before committing, and test on a sandbox/test clock.
Usage billing needs idempotent, deduped metering. Double-counted events = wrong invoices; design the
meter ingestion to be replay-safe.
Don't migrate lightly
Switching billing engines means re-tokenizing payment methods (sometimes a customer re-subscribe),
migrating subscription state + invoice history, and re-wiring webhooks/RevRec. Migrate only for a structural
reason (outgrowing the catalog, needing usage/RevRec, fee at scale), not a small fee delta.
If you discover something not covered here, append it to references/learnings.md with today's date.
Gotchas
Best-effort from research (2026-06) — fees, plans, and feature depth change; verify on each vendor.
A billing engine is NOT a Merchant of Record. Chargebee/Recurly/Maxio/Zuora/Stripe Billing leave you
the seller of record — you register/file/remit tax. Want tax off your plate? That's /sales-merchant-of-record.
"Free" billing tiers have cumulative caps. Chargebee's free Starter covers cumulative billing to ~$250K,
then 0.75% on everything — model TCO, don't assume monthly-free.
Headline price ≠ TCO. RevRec, retention/analytics, and premium integrations are often separate add-ons
($200–$2,000+/mo). Add your gateway's ~2.9% + 30¢ on top — these engines don't process payments.
Usage metering is the hard part. Accuracy, idempotency, and late/duplicate events make or break
usage-based billing — Orb/Metronome/Lago specialize here; bolt-on usage on a subscription-first tool can be shallow.
Self-hosting (Lago) trades fees for ops. No revenue tax, full control — but you own Postgres/Redis,
upgrades, scaling, and uptime. Real cost is engineering time, not license.
Proration + dunning configs are easy to get subtly wrong. Always test on a sandbox / test clock before
relying on credit amounts or retry schedules in production.
/sales-swell — Swell platform help (API-first commerce backend with a native subscription engine — pause/resume, dunning, separate billing/fulfillment schedules; an alternative to bolting a standalone engine onto a separate cart)
/sales-integration — Wiring a billing engine into a CRM, warehouse, or other tools (webhooks, iPaaS)
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Stripe Billing vs a dedicated engine
User says: "We're on Stripe and our subscriptions are getting complicated — should we stay on Stripe Billing or move to Chargebee?"
Skill does: Frames it as complexity-driven, not fee-driven. Stripe Billing stays best for simple flat/per-seat subs at the lowest cost; a dedicated engine like Chargebee makes sense once you need flexible catalog modeling, hybrid/usage pricing, deep dunning, or RevRec — and it still orchestrates Stripe as the processor. Asks about pricing model + finance needs, then recommends accordingly and routes Chargebee setup to /sales-chargebee.
Result: A complexity-based decision, with the processor kept and billing depth layered on.
Example 2: Usage-based billing engine for B2B SaaS
User says: "We're launching metered, usage-based pricing for an API product. Which billing platform?"
Skill does: Narrows to usage-first engines — Orb/Metronome for accurate event metering, Lago for open-source/self-host, Maxio if usage must tie into RevOps/RevRec. Stresses idempotent, deduped meter ingestion and that subscription-first tools' usage add-ons can be shallow. Recommends a shortlist by team/stage and notes you still own tax (not a MoR).
Result: A usage-billing shortlist matched to metering accuracy and team capacity.
Example 3: Cheapest path for an indie selling globally
User says: "Solo founder, global customers, I just want recurring billing without becoming a tax department."
Skill does: Flags that this is actually a Merchant-of-Record question — a billing engine leaves tax to the seller. Routes to /sales-merchant-of-record for the MoR-vs-Stripe decision, and notes that if they're fine owning tax, Stripe Billing (cheapest) or Zoho Billing (if in Zoho) are the lean billing-engine picks.
Result: Correctly redirected to MoR for the tax-remittance need, with a fallback billing-engine pick.
Troubleshooting
"Customers are churning from failed payments, not cancellations"
Symptom: Revenue leaks but customers aren't actively quitting.
Cause: Involuntary churn — expired/declined cards with weak retry logic.
Solution: Turn on smart, decline-type-aware dunning (retry soft declines aggressively, hard declines once), card-expiry reminders, and a self-serve update-card flow. Recurly specializes here; Chargebee's Smart Retry does decline-aware scheduling. Measure recovered MRR, not just retry count.
"Mid-cycle upgrades produce credits I can't predict"
Symptom: Proration credits vary unexpectedly between changes.
Cause: Credit type and timing depend on the current invoice state (paid vs unpaid) and your proration settings.
Solution: Preview with the engine's estimate API before committing the change, decide explicitly between immediate-charge vs end-of-term, and test on a sandbox / test clock. For Chargebee specifics, route to /sales-chargebee.
"We picked a tool but our usage invoices are wrong"
Symptom: Metered charges don't match real usage.
Cause: Duplicate or out-of-order usage events, non-idempotent meter ingestion.
Solution: Make event ingestion idempotent + deduped (unique event ids, replay-safe), reconcile meter totals against source, and prefer a usage-native engine (Orb/Metronome/Lago) if metering is core. Validate a full billing cycle on a test clock before going live.
