Skip to Content
Docs

Billing Overview

Billing architecture and runtime model for subscriptions and one-time payments.

Overview

Yayaw billing uses a hybrid architecture:

  1. Better Auth Stripe plugin for recurring subscriptions.

  2. Custom Stripe webhook flow for one-time payments (lifetime entitlement).

  3. Runtime config split between environment values and database-managed product metadata.

Source of Truth

  • Environment variables:

    • Stripe secrets

    • Stripe price_id values

  • Database (system_settings + billing product tables):

    • Grace period in system_settings

    • Plan feature limits in billing_plans

    • Product catalog metadata and activation state

    • Organization billing_email and stripe_customer_id

    • One-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_monthly

    • pro_yearly

    • business_monthly

    • business_yearly

  • One-time product:

    • pro_lifetime

Runtime Priority Rules

  1. If the organization has an active pro_lifetime entitlement, billing state is considered active and effective plan is pro.

  2. Otherwise, billing state follows Stripe subscription status and grace-period rules.

  3. 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:

  1. /dashboard/organization/billing (active plan summary + status/seats + activity)

  2. /dashboard/organization/plans (plan selection and checkout actions)

Both surfaces are driven by a dedicated server view-model:

  • getOrganizationBillingPageModel(organizationId)

  • overview.activeOffer is 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 emits invoice.paid, once a paid invoice can be linked from Yayaw email.

Billing templates declare detailed purchase variables, including:

  • billing.productName, billing.planName, billing.productType

  • billing.amountFormatted, billing.currency, billing.billingInterval

  • billing.optionsSummary, billing.lineItemsSummary, billing.discountSummary

  • billing.status, billing.periodStart, billing.periodEnd

  • billing.checkoutSessionId, billing.stripeSubscriptionId, billing.stripePaymentIntentId

  • billing.invoiceId, billing.invoiceNumber, billing.invoiceUrl, billing.invoicePdfUrl, billing.billingReason

  • billing.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:

  1. Current subscription snapshot

  2. Lifetime entitlements (billing_entitlements)

  3. One-time webhook events (billing_webhook_events, provider stripe-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 customer to 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_id inside the same advisory-locked transaction.

  • Missing Stripe price_id values mark products as non-checkoutable instead of crashing runtime.