Configure subscriptions and credit packs

The plans are reference data

The billing demo shows the SaaS plans from app/core/product.ts. It is not a template license price. Set your actual amounts, allocation rules and supported workflows before accepting payments.

Choose and configure one provider

1. Set the product billingProvider and runtime BILLING_PROVIDER to waffo, stripe or creem.
2. Start with BILLING_MODE=test.
3. Create matching platform products/prices and add test:<planId> mappings to product.prices. Stripe requires a Price ID, not its Product ID.
4. Supply Waffo Merchant/Store IDs, merchant private key and platform webhook public key; or Stripe Secret Key and Webhook Secret; or Creem API Key and Webhook Secret.
5. Register the selected endpoint: APP_URL/api/webhooks/waffo, /stripe or /creem.

Keep test/live keys, platform products, mapping prefixes and callbacks separate. Full key names and retrieval instructions are in the repository README. Configuration explains storage locations.

Understand credits and recovery

Website, API and Skill share a user's credits. A task reserves credits, success settles the reservation, confirmed failure releases it, and an unknown result holds it pending reconciliation. Current reference charges are fixed per task.

Subscription allocations are monthly; annual paid periods release monthly allocations within the confirmed period. Top-ups are permanent under current reference rules. Changing those rules requires corresponding ledger and user-documentation changes.

Prove payment before granting access

A checkout return URL is not payment proof. Validate signed callbacks, order amount/currency/product, duplicate and out-of-order events, renewals, arrears, cancellation and refunds. An application credit adjustment is not a money refund. Only mark sandbox or production verified after a real provider flow is observed.

What happens if a subscription pauses or a callback arrives late?

Paused or unpaid subscriptions cannot spend their subscription credits or receive new annual monthly allocations. Credit packs and free allocations keep their own rules. A newer signed lifecycle update can resume the same paid period; an old status or a repeated receipt cannot override a newer pause. Scheduled cancellation keeps access within the confirmed period. Fully refunded or disputed allocations stay revoked.

Creem uses subscription.update, and its subscription payment event may supply a transaction reference without an amount. The server reads that transaction to confirm collected money, currency and subscription binding. It never treats a product's listed price as a receipt.

Waffo scheduled or failed plan changes do not grant the target plan. An applied mapped plan has a separate immutable order snapshot, and requires its matching confirmed payment. Unknown products or unverified prorated amounts remain pending for review. Check the repository billing guide for event contracts and real sandbox acceptance steps.