How Subscriptions End
Cancel at period end and keep it, what deleting an organization does to its subscription, trials that end, failed payments and the payment banner, and what happens to data over a limit after a downgrade.
A subscription ends in one of four ways: a billing manager cancels it, the organization is deleted, a trial runs out, or Stripe gives up on a failed payment. This page says what the kit does in each case and what you can change.
Records After Account Deletion
Deleting a personal account or organization retains subscription tracking while Stripe still has it live, including subscriptions scheduled to end at period end. After checking the current Stripe subscription and matching its customer, the kit clears period and entitlement details and retains the identity record. This keeps delayed Checkout events recognizable after the account is gone. It keeps tracking during provider failures or while billing is disabled.
The billing-reconciliation cron runs every 15 minutes. It schedules at most 100 orphan subscription checks per tick; claimed rows move an hour ahead so retained rows cannot block later candidates. Confirmed-ended identities are excluded from the scheduling index and are not polled again. A different Stripe subscription id still gets checked. Scheduling state and outbox jobs commit together. Candidate discovery checks owner existence and may scan subscription records; the limit bounds updates and jobs, not every row examined.
This also recovers missed termination webhooks. Signed events can fill a pending row's missing Stripe id after verifying the customer; a different subscription gets independent tracking. Rows without a known Stripe subscription id stay until an event establishes that identity. Do not add subscription.referenceId to unconditional owner purge targets: doing so loses billing recovery. Identity records remain without a time limit so delayed deliveries can be handled; Stripe customers and invoices remain in Stripe.
Cancel and Keep
On /settings/billing, Cancel subscription opens a dialog saying the user is redirected to Stripe to confirm; Continue to Stripe then opens Stripe's cancel page for the account's subscription. Once confirmed, the subscription stays active until the end of the period already paid for, and the card says Ends on that date. Until then, Keep subscription undoes it: the card says Renews on again, nothing is charged twice, and nothing goes through Stripe Checkout.
- Who: members with
billing:updateon the organization (owners and admins by default), and the user on their own personal account. Everyone else sees neither button, and a forged request is refused before Stripe (Roles and Permissions). - Never right away. Cancelling always ends at period end with no proration, and no refund. There is no self-serve immediate cancel; refund or end a subscription early from the Stripe Dashboard.
- Trials: cancelling a trial ends it at the trial's end, with no charge.
- Payment problems: a
past_dueorunpaidsubscription can be cancelled, but not kept: Keep subscription is hidden until the card is fixed in Manage billing (the page says so). - Stripe Dashboard: Stripe's cancel page is a customer portal flow, so the portal's cancellation setting must allow it at period end.
pnpm billing:setupsets Cancel subscriptions to at the end of the billing period, no proration, andpnpm billing:doctorflags it if it drifts (Setup). The portal's own Cancel button does the same thing for anyone who can open the portal.
The row changes when Stripe's webhook lands, a few seconds after the customer comes back; the page tells them so in the meantime.
Deleting an Organization
Deleting an organization ends its subscription in Stripe first, after the emailed code and before anything is deleted. The delete dialog tells the owner how it will end, with no refund. onDelete in apps/web/config/billing.config.ts decides how:
export const billingConfig = defineBillingConfig({ // … onDelete: { mode: 'immediately', prorate: false }, // the default});onDelete | What happens |
|---|---|
{ mode: 'immediately' } (default) | Cancelled right away, with a final invoice that bills any metered usage of the period. No proration, no refund. |
{ mode: 'immediately', prorate: true } | Cancelled right away; Stripe credits the unused time to the customer's balance. Still never a refund. |
{ mode: 'period_end' } | Set to end at the end of the paid period. It runs out on its own; nothing renews. prorate isn't allowed with it. |
- If Stripe fails or times out, nothing is deleted and the owner sees "try again in a few minutes"; they request a new code.
- If Stripe cancels but the delete then fails, the organization stays, on the default plan; trying again finds nothing left to cancel.
- With billing off (no Stripe keys) and a subscription still billing, the delete is refused with "contact support": nothing could cancel it.
- Not covered: a subscription created in the Stripe Dashboard that the app never stored. Cancel those in Stripe.
The kit's lifecycle job also cancels, at once, any subscription whose organization or user no longer exists, except one already set to end at period end. Mechanics: Authorization Policies.
Deleting an Account
A user deleting their own account runs the same step for their own (personal) subscription and for each organization deleted with them, after the emailed code and before the delete (Deleting Your Account). onDelete, the failure behaviour and billing-off rule above apply unchanged. The dialog says how each ends. If the delete is refused after a cancel (an organization gained a member meanwhile), the account stays: on the default plan with immediately, on its paid plan until the period ends with period_end.
Trials That End
A trial (freeTrial on a plan, Plans) turns into a paid subscription at its end unless it was cancelled.
- With a card (the default), Stripe charges it at the trial's end.
checkout.trialWithoutCard: truestarts the trial without asking for a card. If none is added by the trial's end, Stripe cancels the subscription and the account drops to the default plan.- Reminder emails are Stripe's. Turn on Settings → Billing → Subscriptions and emails → Send a reminder email 7 days before a free trial ends in the Stripe Dashboard (per mode). The kit sends no trial emails.
Failed Payments
When a renewal fails, Stripe retries it on its own schedule (Settings → Billing → Subscriptions and emails → Manage failed payments, where you also choose what happens after the last retry and turn on Stripe's failed-payment emails).
- Status: the subscription becomes
past_duewhile Stripe retries, thenunpaidorcanceledas your Stripe settings say. - Access: by default
past_duekeeps the plan (gatingStatuses: active, trialing, past_due) andunpaiddrops to the default plan (Gating). - The banner: while the active account is
past_dueorunpaid, members withbilling:update(and the user on their own account) see "Your last payment failed" at the top of every app page, with Fix billing to/settings/billing. Others never see it. Dismissing it hides it for the browser session; it comes back in a new one while the problem lasts. It reads one row per page view and never calls Stripe. It lives in both app layouts (<PaymentProblemBanner />): keep it if you restyle them. - Your code: the
paymentFailedhook runs once per failure (Hooks).
After a Downgrade or an End
When a plan ends or drops to a smaller one, the account's data stays as it is. New creates over a limit are refused by requirePlanLimit in your actions, and features off the plan by requireFeature (Gating). Nothing is deleted or locked: an account with 10 projects on a plan that allows 3 keeps all 10 and can't add an eleventh, or a fourth once it's back under. If you want a read-only mode or a cleanup, that is your code, gated on the same checks.
Recipe: a "Cancellation Scheduled" Email
Stripe's emails cover receipts, trials and failed payments, not a cancellation. To send your own when a subscription is set to end, add a subscriptionUpdated hook that enqueues an outbox job, keyed by the event:
// apps/web/config/billing-hooks.config.server.tsimport { db } from 'void/db';import type { BillingHooks } from '@kit/billing/server';import { cancellationScheduledEmail } from '#/jobs/cancellation-scheduled-email.job.ts';export const billingHooks: BillingHooks = { subscriptionUpdated: [ async ({ eventId, subscription, getOutbox }) => { await getOutbox().transaction(db, (_tx, enqueue) => enqueue(cancellationScheduledEmail, { payload: { stripeSubscriptionId: subscription.stripeSubscriptionId }, dedupeKey: `cancellation-scheduled:${eventId}`, }), ); }, ],};The job reads the row when it runs (the event may be stale or out of order) and sends only while the subscription is set to end:
// apps/web/jobs/cancellation-scheduled-email.job.tsimport { defineOutboxJob, ok, retry } from '@kit/outbox/server';import { db, eq } from 'void/db';import { sendEmail } from 'void/email';import { z } from 'zod';import { subscription } from '#/db/schema.ts';import { renderEmail } from '#/config/emails.server.ts';import { billingContactOf } from '#/lib/billing-contact.server.ts'; // yoursexport const cancellationScheduledEmail = defineOutboxJob({ kind: 'app.cancellation-scheduled-email', payload: z.object({ stripeSubscriptionId: z.string() }), timeoutMs: 30_000, async handle({ stripeSubscriptionId }) { const [row] = await db .select() .from(subscription) .where(eq(subscription.stripeSubscriptionId, stripeSubscriptionId)); const ending = row && (row.cancelAtPeriodEnd || row.cancelAt); if (!ending) { return ok(); } // { email, locale } of who should hear about it (an owner, the user) const contact = await billingContactOf(row.referenceId); const email = await renderEmail({ template: 'cancellationScheduled', to: contact.email, locale: contact.locale, data: { endsOn: (row.cancelAt ?? row.periodEnd)?.toISOString() ?? '' }, }); if (!email) { return ok(); } const result = await sendEmail({ to: contact.email, ...email }); if (!result.ok && 'error' in result) { return retry({ code: result.error.code, after: 60_000 }); } // otherwise sent, or its one recipient failed (result.deliveries: an // invalid address): a retry wouldn't help return ok(); },});- Add the
cancellationScheduledtemplate toapps/web/config/email-templates.server.tsx(defineEmailTemplate, its copy inapps/web/messages/<locale>/emails.server.json, a body from@kit/email-templates). - List the job in
apps/web/config/outbox.config.server.ts(Jobs). eventIddedupes Stripe's retries of one event. AnothersubscriptionUpdatedwhile the subscription is still ending (Stripe changes the period, for example) is a new event: to send exactly once per cancellation, key onstripeSubscriptionIdplus the end date instead, or record what you sent.- Check
result.error(the request failed: retry) andresult.deliveries(a recipient failed: retrying won't help). Cloudflare email has no idempotency key, so send to one recipient per job: a retry then never emails someone twice.