Subscriptions & Billing

This page documents the MVS-owned billing layer: the catalog (Product, Price), the customer record (BillingCustomer), recurring subscriptions (BillingSubscription + BillingSubscriptionItem), invoices (BillingInvoice), and the checkout funnel (CheckoutSession + CheckoutSessionItem). All of these models live in the dedicated mvs-pay extensions database (packages/mvs-pay/prisma/schema.prisma) and are served by the Next.js route handlers under apps/mvs-pay/app/api/billing/.

The billing data model

Seven models plus their enums make up the billing layer. Everything is tenant-scoped by organizationId (or, for Price, transitively through its parent Product), and every route enforces that scope explicitly with where: { organizationId } — there is no row-level security in Postgres (see Authentication & Tenancy).

Product & Price (the catalog)

A Product is a sellable thing scoped to an org and uniquely keyed by (organizationId, slug). A Price attaches money and recurrence to a product. The split mirrors Stripe’s catalog: one product can carry many prices (monthly, annual, per-seat), and prices are immutable enough that they should be retired, not edited, once referenced by a subscription.

The catalog routes:

POST /api/billing/prices re-resolves the parent product under the caller’s org before creating the price, so a caller cannot mint a price under another tenant’s product. The same defensive re-scoping is done in POST /api/billing/subscriptions for the customer.

ProductFeature (entitlements, schema-only)

ProductFeature models entitlements hung off a product — keyed by (productId, featureKey), typed BOOLEAN / METERED / STATIC (PaymentFeatureType), with an optional includedUnits. It is returned by GET /api/billing/products/[id] but there is no API to create, update, or enforce features today, and no metering integration wired to it. The openMeterCustomerId / openMeterSubscriptionId / openMeterInvoiceId columns scattered across BillingCustomer, BillingSubscription, and BillingInvoice point at the same unrealised OpenMeter usage-metering integration: the columns exist, nothing populates them.

BillingCustomer

The local customer record, unique per org by (organizationId, email). It holds contact details, a billing address, tax exemption flags/IDs, and the Hyperswitch linkage (hyperswitchCustomerId, hyperswitchPaymentMethodId).

BillingSubscription & BillingSubscriptionItem

The recurring-revenue heart of the layer. A subscription belongs to one BillingCustomer, carries a status, a billing period window, trial dates, cancel intent, and payment-retry / revenue-recovery bookkeeping. Its line items (BillingSubscriptionItem) each reference a Price with a quantity.

The revenue-recovery fields are written not by these billing routes but by the extensions service: apps/mvs-pay-extensions/src/routes/webhooks-revenue-recovery.ts updates them when Hyperswitch posts a retry-resolution webhook. See Revenue Recovery and ADR-011 · Revenue Recovery.

The subscription state machine

BillingSubscriptionStatus defines eight states:

INCOMPLETE · INCOMPLETE_EXPIRED · TRIALING · ACTIVE
PAST_DUE · CANCELED · UNPAID · PAUSED

New subscriptions default to INCOMPLETE. The canonical “recurring revenue” arc the prompt and schema describe is ACTIVE → PAST_DUE → UNPAID: a healthy subscription whose renewal payment fails moves to PAST_DUE while dunning/recovery retries run, and if recovery ultimately fails it lands in UNPAID.

The three lifecycle action routes

All three follow an identical, tenant-safe shape: a single updateMany keyed by { id, organizationId } (so a wrong tenant simply matches zero rows → 404), followed by a re-fetch of the updated row.

BillingInvoice

BillingInvoice records a billed amount against a customer and (optionally) a subscription. BillingInvoiceStatus is DRAFT / OPEN / PAID / VOID / UNCOLLECTIBLE, defaulting to DRAFT. Amounts are stored in minor units (subtotal, tax, total, amountPaid, amountDue), lineItems is a required JSON blob, and hyperswitchPaymentIntentId links the invoice to the payment that settled it.

CheckoutSession (the funnel)

CheckoutSession is the funnel object that would carry a buyer from a hosted payment page to a paid subscription or one-off payment. Its enums:

• PaymentCheckoutMode — PAYMENT (one-off), SUBSCRIPTION, SETUP (collect a payment method, no charge).
• PaymentCheckoutStatus — OPEN (default), COMPLETE, EXPIRED.

Key fields include successUrl/cancelUrl, the Hyperswitch HyperLoader handoff (hyperswitchPaymentIntentId, hyperswitchClientSecret, hostedCheckoutUrl), amountTotal, an expiresAt, and the outcome pointers resultingSubscriptionId / resultingPaymentIntentId. Line items (CheckoutSessionItem) reference a Price with a quantity.

Hosted checkout & portal (501 today)

Two endpoints are intentionally honest 501 NOT_IMPLEMENTED responses rather than silent calls to a decommissioned gateway:

• POST /api/billing/checkout-sessions
• POST /api/billing/customers/[id]/portal-session

Both still authenticate (returning 401 if there is no session) before returning 501 with the message "not implemented: hosted checkout/portal backend not yet available".

How billing routes are wired

Every handler under apps/mvs-pay/app/api/billing/ is a Next.js App Router route that resolves its database client and tenant through one chokepoint: getPaymentsContext() from apps/mvs-pay/lib/payments-db.ts.

1
const ctx = await getPaymentsContext();
2
if (!ctx) {
3
  return NextResponse.json(
4
    { error: { code: "UNAUTHORIZED", message: "Not authenticated" } },
5
    { status: 401 },
6
  );
7
}
8
// ctx.db            → the shared dedicated mvs-pay Prisma client
9
// ctx.organizationId → the tenant scope applied to every query
10
const products = await ctx.db.product.findMany({
11
  where: { organizationId: ctx.organizationId },
12
});

A few consequences worth internalising as the new owner:

• Single shared database, query-level tenancy. Post-cutover (C3.2) the context resolves one shared @mvs/mvs-pay/client, not a per-tenant client. Isolation is enforced by the explicit where: { organizationId } on every read and by updateMany({ where: { id, organizationId } }) on every write. Drop that clause and you leak across tenants — there is no database backstop. See Authentication & Tenancy and Data Model.
• Consistent error envelope. Handlers return { error: { code, message } } with 401 (no session), 400 (INVALID_BODY), 404 (NOT_FOUND — including the zero-match updateMany case), 500 (*_FAILED), and 501 (NOT_IMPLEMENTED) for the two hosted stubs. Success bodies are unenveloped JSON; collection responses include { total, limit, offset, hasMore }.
• No request-body validation library. Validation is hand-rolled typeof checks per handler (e.g. slug/name for products, unitAmount for prices, email for customers, customerId for subscriptions). There is no shared Zod schema for billing payloads.

Where this sits relative to Hyperswitch

The billing layer is MVS-canonical, but it is meant to ride alongside Hyperswitch via the ID columns, not replace it:

The links are aspirational where the wiring is missing: as noted, the create routes do not yet populate hyperswitchCustomerId or call Hyperswitch to mint a mandate, and no worker charges those mandates on renewal. The recurring-payment recovery side of the loop is the most built-out integration — driven by Hyperswitch’s Revenue Recovery and recorded back onto BillingSubscription.

Owner’s checklist: what is real vs. provisioned