How subscription billing and the renewal lifecycle work

This page explains how MapleGather manages recurring membership billing from when a subscription is created to when a renewal charge fails and the dunning process begins.

How it works

MapleGather manages recurring billing through subscriptions. When a renewal date arrives, MapleGather instructs Stripe to charge the member’s card on file. If the charge fails, a dunning (retry) process begins. The sections below explain each stage.

Subscription basics

A subscription links a member to a membership level and controls when and how that member is charged. When a subscription is active:

The member’s status is active for the associated membership.
MapleGather tracks the current billing period and the next renewal date.
Stripe holds the member’s saved card on file (via a Stripe Customer record) and charges it automatically at renewal.

A member can have at most one subscription per membership level in your org. If you offer multiple levels (for example, Student and Professional), a member can hold one subscription per level.

What happens at renewal

When a subscription’s renewal date arrives:

MapleGather instructs Stripe to charge the card on file.
Stripe attempts the charge.
If it succeeds: Stripe notifies MapleGather via webhook. MapleGather marks the invoice as paid, updates the billing period to the next cycle, and fires a renewal receipt to the member.
If it fails: Stripe notifies MapleGather of the failure with a decline reason. MapleGather starts the dunning lifecycle.

The dunning lifecycle

When a renewal charge fails, MapleGather enters a dunning window — a configurable retry period to recover the payment before cancelling the subscription.

During dunning:

The member’s subscription status changes to past due.
MapleGather fires a dunning notification email and shows a warning banner in the member’s billing portal (“Your renewal payment failed — update your card to continue your membership”).
Stripe retries the charge at intervals controlled by your dunning settings (either smart adaptive timing or fixed 5-day spacing).
Each retry attempt optionally sends a new dunning notification with per-attempt copy you can customize.

Dunning ends when:

The payment succeeds — the subscription moves back to active, the invoice is marked paid, and a receipt fires. The dunning banner clears automatically.
The member updates their card and the next retry succeeds — same outcome as above.
The retry limit is reached — by default, 4 attempts over 21 days. If no successful charge occurs, the subscription is cancelled and the member’s status changes to Lapsed. See Membership statuses reference for what Lapsed means for member access.

Your org can configure the retry limit (1–4 attempts) and the dunning window length. See Configure recurring billing and dunning settings.

Pausing and cancelling subscriptions

Admins can pause a subscription to temporarily stop automatic charges without cancelling the member’s record. A paused subscription does not retry charges and does not accumulate overdue invoices. Pausing is appropriate when a member requests a leave of absence.

Admins can cancel a subscription either at the end of the current billing period (the member’s access continues until then) or immediately (access stops the same day). Cancellation is irreversible — to resume a cancelled subscription, you must create a new one.

Member-side visibility

Members see their subscription status, next renewal date, and current billing period in their billing portal. If a renewal payment fails, the dunning banner appears there with a link to update their card. Once the payment succeeds, the banner clears automatically.