πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
Billing
Overview
Stripe Billing powers subscriptions and usage-based pricing for organizations. We primarily use the new flexible billing model (plan + usage) and still handle legacy, single-item metered subscriptions during migration.
Key Concepts
- Organizations: Entities within the product that can have multiple projects.
- Projects: Sub-entities under organizations where usage is tracked.
- Observations: Units of usage (API calls), tracked at project level and aggregated for billing per organization.
Implementation Details
API Surface (TRPC)
See web/src/ee/features/billing/server/cloudBillingRouter.ts.
getSubscriptionInfoβ live cancellation/scheduled-change info from Stripe.createStripeCheckoutSessionβ starts checkout for a product from the catalogue.changeStripeSubscriptionProductβ switches plan (upgrade now, downgrade at period end).cancelStripeSubscription/reactivateStripeSubscriptionβ manage cancellation flags.clearPlanSwitchScheduleβ releases any active/not-started schedule.getStripeCustomerPortalUrlβ portal for payment methods, tax IDs, invoices (not for plan switches).getInvoicesβ paginated invoice list with subscription/usage/tax breakdown and preview row.
The billing page also embeds the usage breakdown chart from web/src/features/organization-usage (MIT, organizationUsage.breakdown). It counts units with the same created_at definition as metering. Self-hosted deployments show the same chart on the organization's Usage settings page instead.
Checkout and Subscription Management
Implemented in web/src/ee/features/billing/server/stripe/stripeBillingService.ts.
Checkout
- Initiated from billing settings; only products from the catalogue are allowed.
- For flexible billing, the session includes two items: plan (quantity 1) + usage.
subscription_data.billing_modeis set to flexible; metadata carriesorgIdandcloudRegion.
Plan Changes
- Upgrades: immediate price swap with proration invoiced now; release any schedules first.
- Downgrades: create a subscription schedule to switch at current period end; release existing schedules first.
- Legacy handling: migrate classic subscriptions to flexible; replace single metered item with plan+usage or vice versa.
Cancellation / Reactivation
- Cancel sets
cancel_at_period_end(or clearscancel_at); reactivate clears cancellation flags. - Both release any active/not-started subscription schedules first.
- Cancel sets
Cloud Config
cloudConfig.stripe:customerId,activeSubscriptionId,activeProductId,activeUsageProductId.- Entitlements derive from
activeProductIdand catalogue mapping. - If
planis set (manual override), creating/changing subscriptions is blocked until removed.
Usage-Based Pricing
Usage Meter in Stripe
- Usage is tracked at the Stripe customer level via a meter on the usage item.
- The worker reports usage periodically for all orgs with a Stripe customer.
Hourly Job
- Runs in the worker (
cloudUsageMeteringQueue). - Aggregates last-hour observations and posts to Stripe usage.
- Governed by BullMQ repeatables and
cron_jobstable to ensure singleton execution/backfill.
- Runs in the worker (
Webhooks
See web/src/ee/features/billing/server/stripe/stripeWebhookHandler.ts.
- Validates signature; ensures events are handled only in the correct
cloudRegion. - Ensures subscription metadata (
orgId,cloudRegion) is set (falls back to checkout session lookup if needed). - On subscription created/updated: writes
customerId,activeSubscriptionId,activeProductId,activeUsageProductIdto orgcloudConfig; on deleted: clears active IDs. - On
invoice.created: recreates usage alert to make alerts fire once per billing period. - On
billing.alert.triggered: emails admins/owners and configured recipients. - Invalidates org API keys after subscription changes.
Testing
Lightweight guidance for local/staging testing. Stripe docs are solid references.
- Create a test clock in the Stripe sandbox
- Use the Stripe Dashboard Test Clocks page: Test Clocks.
- Create up to three users tied to the clock (e.g., "Test User A", "Test User B").
- Prepare an organization in your environment (local or staging)
- Insert the Stripe customer on the org DB by setting
cloudConfigto:
- Insert the Stripe customer on the org DB by setting
{ "stripe": { "customerId": "cus_T2dbT3t6hyp9RE" } }
- Note: Required because test clocks cannot be used with existing customers; first create them on the clock.
- Local-only notes
- Build and run without dev hot-reload to avoid dropped webhook events:
NODE_OPTIONS="--max-old-space-size=8192" pnpm build && pnpm start
- Listen to webhooks:
stripe listen --forward-to localhost:3000/api/billing/stripe-webhook
- Staging notes
- Ensure
STRIPE_WEBHOOK_SIGNING_SECRETandSTRIPE_SECRET_KEYpoint to sandbox and have correct permissions.
- Ensure
- Exercise scenarios
- Use Stripe Workbench β Shell to send meter events; advance the test clock (only forward in time).
- Change subscriptions from the UI; advance time; send events; verify invoices/alerts.
- Events must be sent with the current date of the test clock.
Current Limitations
- The Stripe Billing Portal cannot be used for plan switches. Plan changes must go through our API. The client shows an alert explaining implications but does not present a dedicated checkout page for switching plans.
- Stripe is rolling out a v2 of usage-based billing APIs (private beta as of 2025-09). If revisited, consider adopting v2 to reduce maintenance and custom logic.