Subscriptions

Subscriptions are the Stripe-native recurring billing flow. Each subscription ties a Customer to a Stripe price, optionally with a trial, quantity, and metadata. Lifecycle events (created, updated, paused, canceled, trial-ending, payment-failed) flow through a Stripe webhook into the api service which mirrors them onto local rows so the rest of the platform doesn't need to call Stripe for every read. Proration on plan change is delegated to Stripe.

Use subscriptions when the customer pays a card directly. For invoice-and-pay flows on a schedule, use Recurring invoices instead.

Related endpoints

• GET /api/tenant/subscriptions — list.
• POST /api/tenant/subscriptions — create on Stripe + mirror locally.
• POST /api/tenant/subscriptions/:id/cancel — at period end (default) or immediate.
• POST /api/tenant/subscriptions/:id/change-plan — proration via Stripe.
• POST /api/control/webhooks/stripe — webhook ingest (HMAC-verified).

See the source at apps/web/src/app/(tenant)/subscriptions and apps/api/src/subscriptions.