Billing Overview
Billing architecture and runtime model for subscriptions and one-time payments.
Overview
Yayaw billing uses a hybrid architecture:
Better Auth Stripe plugin for recurring subscriptions.
Custom Stripe webhook flow for one-time payments (lifetime entitlement).
Runtime config split between environment values and database-managed product metadata.
Source of Truth
Environment variables:
Stripe secrets
Stripe
price_idvalues
Database (
system_settings+ billing product tables):Grace period in
system_settingsPlan feature limits in
billing_plansProduct catalog metadata and activation state
Organization
billing_emailandstripe_customer_idOne-time entitlements and webhook idempotence events
Yayaw is the source of truth for billing contact email. Stripe Customer email is synchronized from the organization billing email, falling back to the checkout actor's account email when the organization has no explicit billing email. Stripe customer details are never used to change the user's login email.
Current V1 Product Model
Subscription products:
pro_monthlypro_yearlybusiness_monthlybusiness_yearly
One-time product:
pro_lifetime
Runtime Priority Rules
If the organization has an active
pro_lifetimeentitlement, billing state is considered active and effective plan ispro.Otherwise, billing state follows Stripe subscription status and grace-period rules.
Seat enforcement still applies using the effective plan seat limit.
Organization Billing UX Model (V2.3)
The organization billing UX is split into two dashboard surfaces:
/dashboard/organization/billing(active plan summary + status/seats + activity)/dashboard/organization/plans(plan selection and checkout actions)
Both surfaces are driven by a dedicated server view-model:
getOrganizationBillingPageModel(organizationId)overview.activeOfferis resolved server-side (free,pro_subscription,business_subscription,pro_lifetime)product CTA states are resolved server-side (
enabled/disabled + reason)product cards include Stripe price mirrors, billing intervals, plan limits, marketing features, and active-offer highlighting
checkout client executes only action kinds declared in the view-model (
subscription_checkout,one_time_checkout,billing_portal)the Stripe billing portal action stays disabled until the organization has a recorded Stripe customer, which avoids exposing a portal action before the first successful checkout
organization settings expose a billing contact card; saving it updates the stored billing email and synchronizes any existing Stripe Customer
checkout requests pass the active locale through to Stripe so Checkout and follow-up billing emails can use the right locale context
This prevents business-rule drift between server and client.
Checkout Success
Checkout success redirects to
/dashboard/organization/billing?checkout=success... so the customer lands on
the billing summary after purchase confirmation. For one-time payments, the
confirmation checks for a billing_entitlements row recorded for that Stripe
checkout session.
Billing Transactional Emails
Billing webhooks send transactional emails through database-managed system
templates when RESEND_API_KEY and active templates are available. Missing
email configuration or missing templates are logged and do not fail webhook
processing.
Built-in billing template slugs:
billing-purchase-confirmation: sent after successful subscription checkout and after successful one-time lifetime checkout.billing-subscription-updated: sent when a subscription cancellation is scheduled or when Stripe confirms subscription deletion.billing-invoice-available: sent after Stripe emitsinvoice.paid, once a paid invoice can be linked from Yayaw email.
Billing templates declare detailed purchase variables, including:
billing.productName,billing.planName,billing.productTypebilling.amountFormatted,billing.currency,billing.billingIntervalbilling.optionsSummary,billing.lineItemsSummary,billing.discountSummarybilling.status,billing.periodStart,billing.periodEndbilling.checkoutSessionId,billing.stripeSubscriptionId,billing.stripePaymentIntentIdbilling.invoiceId,billing.invoiceNumber,billing.invoiceUrl,billing.invoicePdfUrl,billing.billingReasonbilling.manageUrl
Templates saved before purchased code access was removed may still reference
billing.accessUrl and billing.deliverablesSummary. The system templates no
longer declare them, but the variable builder still emits billing.accessUrl
(the billing dashboard URL) and an empty billing.deliverablesSummary so those
templates keep rendering.
One-time purchases send to the checkout actor first, then the Stripe checkout
email, then the organization fallback. Subscription purchase emails use the
Better Auth Stripe checkout metadata userId first, then Stripe checkout email,
then the same organization fallback. Subscription updates use the
subscription's userId metadata, then the fallback; invoice emails use the
invoice's actor metadata, then the invoice customer email, then the fallback.
The actor receives the email only while they are still a member of the
organization and can() grants them billing:read there: an actor who left
the organization, or who lost that permission, receives nothing, and the email
goes to the next recipient in that order. The invoice customer email is the
Stripe Customer email, which is the checkout actor's account email while the
organization has no billing email of its own; save a billing contact so later
invoices do not reach someone who left the organization.
The fallback is the organization's longest-standing member for whom can()
grants billing:read in that organization, because the email discloses what
that permission shows on /dashboard/organization/billing. A Better Auth role
(owner, admin, manager) qualifies nobody by itself: when no member holds
billing:read, the email is not sent and only the organization id is logged.
Invoice emails resolve the organization from invoice metadata first,
subscription metadata second, and local subscription/customer rows last.
One-time Checkout enables Stripe invoice creation and stores organization,
actor, product, plan, and locale metadata on generated invoices. If Stripe
native receipt or paid-invoice emails are enabled, customers may receive both
Stripe and Yayaw email for the same invoice.
Activity Timeline Scope
The timeline intentionally exposes internal billing activity, not a full Stripe invoice ledger:
Current subscription snapshot
Lifetime entitlements (
billing_entitlements)One-time webhook events (
billing_webhook_events, providerstripe-one-time)
One-time webhook items are filtered by organizationId from persisted Stripe payload metadata.
Safety Rules
One-time checkout is blocked when an organization already has a non-canceled active Stripe-backed subscription with a recorded Stripe subscription ID.
One-time checkout creates or reuses the organization Stripe Customer and passes
customerto Stripe Checkout. When the Customer has a valid email, Checkout pre-fills and locks the email field.One-time webhook processing is idempotent via persisted event IDs, and a purchase is deduplicated by the entitlement's
stripe_checkout_session_idinside the same advisory-locked transaction.Missing Stripe
price_idvalues mark products as non-checkoutable instead of crashing runtime.