/subscription-lifecycle

name: subscription-lifecycle
description: Covers everything after the subscription is created — trials, proration on upgrade and downgrade, dunning and retry schedules, grace periods, involuntary churn from expired cards, cancellation timing, and the bank-mandate lifecycle for SEPA, Bacs, PAD, UPI AutoPay and Pix Automatico. Also covers the stored-credential framework and the network transaction id that recurring charges must carry. This is the part every payment tutorial stops short of, and where production subscriptions actually break.
when_to_use: |
  - Generating or reviewing subscription billing
  - The user asks about trials, proration, dunning, failed payments, cancellation or churn
  - A recurring integration uses a bank mandate rather than a card
allowed-tools: Read, Glob

subscription-lifecycle

Creating a subscription is one API call. Everything that follows is where the money is lost.

The state machine nobody draws

trialing ──► active ──► past_due ──► canceled
    │           │  ▲         │
    │           │  └─────────┘  (retry succeeded)
    │           ▼
    │       paused / grace
    └──► canceled (trial abandoned)

`past_due` is the state that matters. A subscription there is still delivering value and no longer being paid for. How long you tolerate that, and what the customer sees while it lasts, is a product decision the code has to encode explicitly — the default of "keep serving forever because nobody wrote the branch" is the expensive one.

Involuntary churn is the biggest line item

Most subscription cancellations are not decisions. They are expired cards, changed cards, and issuer declines on a merchant-initiated transaction. Concretely:

• **Retry on a schedule, not immediately.** Same-day retries mostly fail again. Spread them

over days, and stop before the issuer starts treating you as abusive.

• **Ask before it breaks.** A card expiring next month is knowable this month.
• **Use account updater** where the provider offers it — the issuer tells them the new number.
• **Distinguish soft from hard declines.** "Insufficient funds" is worth retrying on payday.

"Stolen card" is not worth retrying at all, and retrying it looks like testing stolen cards.

The stored-credential framework

The first charge is customer-initiated (CIT), with the customer present. Every later charge is merchant-initiated (MIT), and the networks require it to reference the original.

**Persist the network transaction id from the first charge and send it on every subsequent one.** Mastercard requires the stored Trace ID on economically-related MITs from 23 October 2026, and Visa's Original Transaction ID already drives approval rates today. An unlinked MIT is not a warning — it is a decline.

That means a column: `network_transaction_id` on the stored payment method or the subscription. Read `recurring.network_txn_id_required` from the provider entry.

Proration

When a plan changes mid-cycle, someone is owed money. The three defensible answers:

• **Prorate immediately** — credit the unused portion, charge the new plan pro rata, invoice

the difference now. Correct, and the most confusing to read on a statement.

• **Prorate at next renewal** — apply the credit to the next invoice. Gentler, and delays revenue.
• **No proration** — the change takes effect at renewal. Simplest, and only acceptable when the

price difference is small.

Pick one, write it down, and make the checkout say what will be charged **before** the click. The support burden of an unexplained mid-cycle charge exceeds its revenue.

Cancellation

Cancel-at-period-end is almost always right: the customer keeps what they paid for, and you keep the revenue you already earned. Immediate cancellation with a refund is a separate, deliberate choice.

Two things that are not optional: cancellation must be possible **without contacting support** (a legal requirement in several markets, not a UX preference), and the customer must be told exactly when access ends.

Bank mandates are a different animal

For SEPA, Bacs, PAD, UPI AutoPay, Pix Automático and PAC, read `fragments/billing/subscription_mandate.md`. The differences that break card-shaped code:

• A mandate has its own lifecycle: created → pending → active, and can take days to activate.
• Advance notice before each debit is legally required — amount and date, days ahead.
• "Successful" is not final. SEPA allows an unauthorised claim for 13 months; Bacs has the

Direct Debit Guarantee. Money can leave weeks after you counted it.

• The payer can revoke the mandate **at their bank**, without telling you. You discover it on

the next failed debit.

Never model these as a card on file. `supports.subscriptions: true` does not mean the rails behave alike.

What a generated subscription integration must include

1. The full state machine, with `past_due` handled explicitly. 2. A dunning schedule with soft/hard decline branching. 3. `network_transaction_id` persisted and sent. 4. A customer portal, or an in-app equivalent, that can cancel without support. 5. Webhook handlers for payment failure, subscription updated and subscription deleted — a subscription cancelled in the provider dashboard must revoke access in your app. 6. For mandates: the pre-notification job and a reversal handler.

Anti-patterns

• Do not create a subscription and consider the feature done.
• Do not retry a failed charge immediately, repeatedly, or forever.
• Do not grant access on a checkout redirect. Grant it on the webhook or a re-fetch.
• Do not treat a mandate rail as a card.
• Do not let a subscription cancelled provider-side keep working in the app.