Membership Subscriptions¶

Revel lets organizations charge recurring membership fees, with three collection modes that share one local state machine:

• OFFLINE: Staff records payments by hand (cash, bank transfer, anything non-Stripe). The grace-expiry Celery beat task drives the state machine.
• ONLINE: Stripe Subscriptions on the org's Connect account. Stripe drives the state machine via webhooks; the local row mirrors what Stripe says.
• FREE (#832): no money at all. Members self-subscribe and the row lands ACTIVE immediately — no Stripe object, no checkout, nothing to collect. FREE plans are necessarily LIFETIME, so nothing ever renews or lapses either. This is the "free but gated" membership: the tier's questionnaire and manual-approval gates still have to pass, which is the whole reason the mode exists (a plan-less tier joins through /apply, which cannot enforce a subscription cap or a paused sale).

The split is captured in ADR-0012; the Stripe Connect model is captured in ADR-0013; the revival flow rules are captured in ADR-0014; the dunning + audit choices are captured in ADR-0015.

Architecture Overview¶

flowchart LR
    subgraph Members["Member-facing"]
        MeAPI["/api/me/...<br>controllers/me_subscriptions.py"]
    end

    subgraph Staff["Staff-facing"]
        AdminAPI["/api/organization-admin/.../<br>controllers/organization_admin/subscriptions.py"]
    end

    subgraph Services["Service layer"]
        Sub[subscription.lifecycle]
        Stripe[subscription.stripe.checkout]
        PlanChange[subscription.stripe.plan_change]
        Dispatch[subscription.stripe.dispatch]
        Report[subscription.reporting]
    end

    subgraph Async["Async"]
        Beat["Celery beat<br>expire_subscriptions_past_grace<br>send_subscription_renewal_reminders<br>reconcile_stripe_subscriptions"]
        Webhook["Stripe webhook<br>stripe_webhook.py"]
    end

    subgraph Data["Data"]
        Plan[(MembershipSubscriptionPlan)]
        SubModel[(MembershipSubscription)]
        Pay[(MembershipPayment)]
        Cust[(CustomerProfile)]
        Member[(OrganizationMember)]
    end

    MeAPI --> Sub
    MeAPI --> Stripe
    AdminAPI --> Sub
    AdminAPI --> Report
    Sub --> Stripe
    Sub --> PlanChange
    Stripe --> Dispatch
    Sub --> SubModel
    Stripe --> SubModel
    Stripe --> Cust
    Stripe --> Pay
    Beat --> Sub
    Webhook --> Stripe
    SubModel -.post_save signal.-> Member

Data Model¶

All in src/events/models/subscription.py. Re-exported via events/models/__init__.py.

MembershipSubscriptionPlan¶

Constraint: unique_plan_name_per_tier(tier, name).

Plan shape rules¶

payment_method constrains price and period_unit. Enforced once in events/utils/subscription_plan_rules.py:validate_plan_shape, called from both PlanCreateSchema (422 at create) and subscription.lifecycle.update_plan (400 at patch, against the merged post-patch values) so the two cannot drift.

Sale controls¶

ensure_plan_on_sale (PAUSED check, member paths only — staff callers pass enforce_sales_status=False) and ensure_plan_sales_capacity (cap check, everyone) live in subscription.lifecycle and are enforced on create, revive and plan switches. The capacity check select_for_updates the plan row so concurrent creations serialize, mirroring the capacity-reclaim invariants of ticket tiers. The public plan schema exposes sales_status and a computed sold_out flag so the frontend can render "sold out" vs "sales paused" vs a normal subscribe CTA.

MembershipSubscription¶

Class attribute TERMINAL_STATUSES = frozenset({"cancelled", "expired"}) is the single runtime source of truth. The same tuple (_TERMINAL_STATUS_VALUES) is referenced from Meta.constraints so the partial-unique index and the runtime check can never diverge.

Constraints / indexes:

• one_active_subscription_per_user_org — partial unique on (user, organization) excluding terminal statuses. Lets a member create a fresh subscription cleanly once a previous one is CANCELLED or EXPIRED.
• Index(organization, status) and Index(user, status) — list/dashboard queries.
• Index(current_period_end) — daily scan in the expiry beat task.

MembershipPayment¶

A payment recorded against a subscription. OFFLINE: created by record_payment. ONLINE: created/upserted by record_stripe_payment_from_invoice on invoice.paid / invoice.payment_failed. The unique-by-side-effect key is stripe_invoice_id (uses update_or_create for webhook idempotency).

CustomerProfile¶

Per-(user, organization) Stripe Customer reference. Created lazily by ensure_customer_profile. Two constraints keep duplicates out: unique_customer_per_user_org(user, org) and unique_stripe_customer_per_org(organization, stripe_customer_id).

Organization additions¶

• membership_grace_period_days (default 7) — how long PAST_DUE lasts before EXPIRED.
• membership_refund_policy — markdown, displayed to members.
• membership_subscription_revival_window_days (default 30) — how long after expired_at revival is allowed. 0 disables revival entirely.

State Machine¶

                    record_payment
PENDING ─────────────────────────────────► ACTIVE ◄───────────────────┐
   │ (ONLINE: invoice.paid)                  │ ▲                       │
   │                                         │ │ resume                │ record_payment / invoice.paid
   │                                pause    ▼ │                       │
   │                                       PAUSED                      │
   │                                                                   │
ACTIVE  ──(period_end<now, !cancel_at_period_end, Celery)──► PAST_DUE ─┘
ACTIVE  ──(period_end<now, cancel_at_period_end=True, Celery)──► CANCELLED (terminal)
PAST_DUE ──(period_end + grace_days < now, Celery)──► EXPIRED            (terminal)

ACTIVE/PAUSED ──(cancel_subscription, immediate=True)──► CANCELLED       (terminal)
ACTIVE/PAUSED/PAST_DUE ──(cancel_subscription, immediate=False)──► (unchanged, cancel_at_period_end=True)

EXPIRED ──(revive_subscription within window)──► ACTIVE (OFFLINE) / PENDING (ONLINE, awaits invoice.paid)

Key invariants:

• Terminal subscriptions (CANCELLED, EXPIRED) never advance their period. record_payment raises 400; _apply_stripe_price_swap short-circuits.
• CANCELLED vs. EXPIRED is the revival discriminator. EXPIRED means an involuntary lapse — expired_at is stamped and the org's revival window applies. CANCELLED means the member (or staff) chose to stop, whether immediately or at the period boundary; expired_at stays NULL and revive_subscription refuses the row. A lapsed ACTIVE row with cancel_at_period_end=True therefore lands CANCELLED, not EXPIRED (_terminalize_cancelled_row), so the member is never offered a "revive?" CTA for a cancellation they asked for.
• Subscription tier wins over member tier on the OrganizationMember sync signal — see Member Sync.
• ONLINE subscriptions in PENDING do not grant ACTIVE membership. The member is only synced ACTIVE once Stripe confirms the first invoice (or the Stripe webhook reports status=active).

Service Layer¶

The service lives in the events/service/subscription/ package: the local state machine at the top level (core, lifecycle, plans, sales, eligibility, uncancel, refunds, reporting, notifications) and the Stripe integration under subscription/stripe/. Every public symbol is re-exported from subscription/__init__.py.

events/service/subscription/lifecycle.py¶

Function-based service that owns the per-subscription OFFLINE flow and the dispatch layer for ONLINE operations. Plan CRUD and price migration live in subscription/plans.py.

events/service/subscription/plans.py¶

Everything that operates on a plan rather than on one subscriber's lifecycle.

events/service/subscription/stripe/checkout.py¶

events/service/subscription/stripe/fees.py¶

The platform's application_fee_percent — the only fee mechanism Stripe offers for subscriptions, so the org fee and the VAT on it are folded into a single percent (effective_application_fee_percent; the fixed fee component does not apply to subscriptions). resync_subscription_application_fees pushes today's percent onto every live ONLINE subscription when an org's VAT status changes, skipping schedule-managed rows (Stripe rejects a plain Subscription.modify while a schedule is attached) and counting per-subscription failures instead of raising.

events/service/subscription/stripe/plan_change.py¶

Extracted from subscription/stripe/checkout.py to stay under the 1000-line file limit. All plan-change logic for ONLINE subs:

• _classify_plan_change normalizes both prices to a per-month figure (_monthly_equivalent_price) before comparing, so a Monthly → Annual swap is classified on per-month cost, not raw headline price.
• _upgrade_online_subscription (more expensive per month): immediate Stripe Subscription.modify with proration_behavior='always_invoice' and payment_behavior='allow_incomplete'. Local plan is swapped synchronously so the API response reflects the change without waiting for the webhook — which is exactly why the proration must be invoiced on the spot rather than merely queued. create_prorations only parks line items on the next invoice, so the member would hold the pricier tier free for a whole cycle, and an immediate cancel (Stripe defaults to invoice_now=False, prorate=False) would discard the delta outright. If the invoice fails, the subscription goes past_due and the normal dunning flow takes over; the price swap stands either way.
• _downgrade_online_subscription (cheaper or equal per month): Stripe SubscriptionSchedule with two phases (current price for the rest of the period; new price after, for a duration of one new-plan billing period — iterations was removed by the pinned Stripe API version). end_behavior='release' falls back to a normal rolling renewal at the new price once that second phase completes. Local row carries pending_plan + stripe_schedule_id until the phase transition arrives via customer.subscription.updated, at which point _apply_stripe_price_swap clears both fields.

events/service/subscription/stripe/dispatch.py¶

Notification dispatch helpers for the Stripe sync/invoice code paths. Holds the gates that prevent double-firing on re-delivered webhooks:

• _dispatch_sync_notifications — gated on transitions captured by prior_status / prior_cap snapshots.
• _dispatch_invoice_notifications — gated on payment_created (from update_or_create) and prior_status so the first invoice of a brand-new subscription does not fire RENEWAL_SUCCEEDED.

events/service/subscription/reporting.py¶

Per-organization metrics for the admin dashboard:

• active_count = ACTIVE + PAST_DUE (still-paying customers).
• mrr = sum, over the active_count subs, of each sub's monthly equivalent. The per-sub amount is the subscriber's latest successful non-proration payment, falling back to plan.price when there is none (OFFLINE pre-payment, brand-new rows) — grandfathered ONLINE subscribers keep paying their old Stripe price, so plan.price alone would overstate them, and a one-off proration charge from a plan change is not a recurring amount. A single batched DISTINCT ON query fetches those amounts, keeping the per-sub loop N+1-free. Annual plans divide by period_count * 12. The sum is quantized once at the end (Decimal("0.01")) to avoid accumulated rounding drift.
• mrr_currency = the shared currency, or "MIXED" (with mixed_currency_warning=True and mrr=0) if the org has subs in multiple currencies.
• churned_30d = subs that transitioned to CANCELLED/EXPIRED in the last 30 days (cancelled_at >= cutoff OR expired_at >= cutoff).
• churn_rate_30d = churned_30d / (active_count + churned_30d) — intentional approximation; see Phase 4 spec §9.

A single aggregate query produces the status breakdown; the MRR loop uses select_related("plan") plus the batched payment lookup above to avoid N+1. LIFETIME plans normalize to 0 monthly: they are one-off, so folding them into MRR would inflate it permanently off a payment that happens once — or, for FREE plans, never.

events/utils/subscription_periods.py¶

Pure utilities:

• calculate_period_end(period_start, plan) — uses dateutil.relativedelta so Jan 31 + 1 month → Feb 28/29 behaves correctly. Explicit branch on plan.period_unit (MONTH / YEAR) so a future unit isn't silently treated as months. Returns None for LIFETIME; callers must propagate that NULL rather than substituting a date. (record_payment is the one place that needs a non-null value anyway — MembershipPayment.period_end is NOT NULL — so a lifetime payment is recorded as the point event it is, period_end == period_start, while the subscription's own current_period_end stays NULL.)
• REMINDER_DAYS = 3 — used by the renewal-reminder beat task.

Permissions¶

A new manage_subscriptions permission on PermissionMap (default: owner ✓, staff ✓, member ✗). Used by OrganizationPermission("manage_subscriptions") on the admin controller. Members access their own subscriptions through the JWT-authenticated MeSubscriptionsController (no permission gate; self.user() scopes every query).

Member Sync (signal)¶

events/signals.py::sync_member_from_subscription listens to post_save on MembershipSubscription:

Rules baked into the signal:

• Never creates a member. Creation lives in create_subscription (OFFLINE and FREE) or _ensure_active_member (ONLINE, gated on the first paid invoice).
• Leaves BANNED alone. A banned member stays banned regardless of subscription activity.
• Subscription tier wins. member.tier is updated to plan.tier on every sync.
• Older terminal rows do not clobber. If a newer non-terminal sub exists for the same (user, org), the signal returns early — re-saving a historical CANCELLED row from the admin must not flip the user back to CANCELLED.

Async Surface¶

Celery tasks¶

All in src/events/tasks/subscriptions.py.

The row-walking tasks materialize their id/row lists with list(), never .iterator() — a server-side cursor cannot survive the per-row commits these loops perform under PgBouncer transaction pooling (see #458 and engineering notes). Each row is then re-loaded under select_for_update + select_related(...), with preconditions re-checked inside the lock, so concurrent record_payment calls or webhook updates cannot be clobbered.

Stripe webhooks¶

events/service/stripe_webhooks.py dispatches subscription events to subscription.stripe.checkout:

A monotonicity guard in record_stripe_payment_from_invoice protects the ledger against out-of-order delivery: a late payment_failed (Stripe gives no ordering guarantee, and a failed→retried→paid invoice emits both events) never downgrades a payment row already recorded as SUCCEEDED.

The webhook endpoint listens to Connect events (see Billing & VAT for the "platform vs. connected" caveat).

API Surface¶

Member-facing (/api/me/...)¶

Staff-facing (/api/organization-admin/{slug}/...)¶

Guarded by OrganizationPermission("manage_subscriptions").

Notifications¶

Seven new types (notifications/enums.py), each with email, in-app, and Telegram templates under notifications/templates/notifications/{email,in_app,telegram}/:

• SUBSCRIPTION_RENEWAL_SUCCEEDED — true renewals only (prior_status ∈ {ACTIVE, PAST_DUE}). Suppressed for first payment and revival payments.
• SUBSCRIPTION_PAYMENT_FAILED — ONLINE: invoice.payment_failed webhook. OFFLINE: ACTIVE → PAST_DUE in the beat task.
• SUBSCRIPTION_EXPIRED — Terminal transition. Includes a revival CTA URL only when the window applies.
• SUBSCRIPTION_CANCELLATION_CONFIRMED — Local row transition only. Webhook does not re-dispatch when the local flag was already set.
• SUBSCRIPTION_RENEWAL_REMINDER — Beat task at period_end - 3 days.
• SUBSCRIPTION_PRICE_MIGRATION_NOTICE — Per affected sub in migrate_plan_subscribers. Skipped when the subscriber's last payment matched the new price already.
• SUBSCRIPTION_REVIVAL_CHECKOUT — Staff-initiated ONLINE revival: staff cannot pay on the member's behalf, so the member is emailed the hosted Checkout link to complete the renewal themselves.

Per-type opt-out via UserNotificationPreference. The Phase 4 migration back-fills default-on preferences for the seven new types across all existing users.

Migrations¶

(The Phase 1 foundation — plan/subscription/payment models, manage_subscriptions permission, events.expire_subscriptions_past_grace beat task — shipped to main earlier and is not part of this branch's migrations.)

Audit¶

HistoricalRecords() on MembershipSubscriptionPlan, MembershipSubscription, MembershipPayment, and CustomerProfile. The admin classes use SimpleHistoryAdmin for a "History" tab with row diffs. History starts at first save after the Phase 4 migration; no backfill. See ADR-0015.

Cross-references¶

• Service Layer — hybrid function/class service pattern this system follows.
• Billing & VAT — Stripe Connect webhook caveat, platform fee model (including subscription platform fees), attendee invoicing (ticket-side only).
• Permissions — OrganizationPermission mechanics that the staff subscription endpoints inherit.
• Notifications — dispatcher and channel selection used by the seven subscription notification types.
• ADRs: 0012, 0013, 0014, 0015.