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. Renewals are not charged automatically today — when a renewal falls due, the member pays it themselves from their billing page, or an admin charges their stored card on their behalf. If that payment fails, the subscription enters a dunning state. Automatic renewal is planned, not running. 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). Renewals are not charged automatically today — having a card on file does not make the membership renew by itself.

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:

The renewal falls due. Nothing charges the card on its own — there is no scheduled renewal charge.
Somebody pays it: the member pays the renewal from their billing page, or an admin charges the member’s stored card on their behalf.
If that payment 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.

Automatic renewal is planned, not running. Until it lands, an unpaid renewal stays unpaid until a member or an admin pays it.

The dunning lifecycle

When a renewal payment fails, the subscription enters a dunning state — the period in which the unpaid renewal is still recoverable, before the membership lapses.

During dunning:

The member’s subscription status changes to past due.
MapleGather shows a warning banner in the member’s billing portal (“Your renewal payment failed — update your card to continue your membership”). The banner names the amount outstanding and offers both ways to clear it: pay the renewal now, or replace the card on file.
Nothing retries the charge on its own today. Your dunning settings record how many attempts to allow, over how many days, and with what per-attempt copy, but no retry executes against that policy yet — retry execution is planned, not running.
No failed-payment (dunning) email is sent yet. The banner is how the member finds out.

Dunning ends when:

The member pays the outstanding renewal — the subscription moves back to active, the invoice is marked paid, and a receipt fires. The dunning banner clears automatically.
The member replaces the card and then pays — same outcome. Saving a new card updates the card on file; on its own it does not settle the unpaid renewal, so the payment is a separate step the member takes on the same page.
The grace period ends without payment — 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, and that policy is stored against your org for the automatic retries it will govern. See Configure recurring billing and dunning settings.

Pausing and cancelling subscriptions

Admins can pause a subscription to temporarily stop charges without cancelling the member’s record. A paused subscription is not billed at its renewal date 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 the amount outstanding and both remedies — pay the renewal, or replace the card on file and then pay. The banner clears once the payment succeeds.

PayPal-funded subscriptions and auto-renew

If your org has PayPal connected, a member can fund their membership with PayPal instead of a card. When a member checks out with PayPal for a membership that renews automatically, MapleGather sets up a PayPal billing agreement so the renewal can be funded through PayPal.

For the member, this looks almost the same as a card-funded membership:

Their billing portal shows the upcoming renewal amount and date, marked via PayPal (there’s no card brand or last four digits, because PayPal is the funding source).
Instead of an “Update card” link, they see a Manage PayPal link.

The one place the experience differs is when a PayPal auto-renew stops working. If the member cancels their PayPal billing agreement — for example, in their own PayPal account — MapleGather can no longer renew the membership with PayPal. Instead of the card-update notice, the member sees a banner: “Your PayPal auto-renew was canceled — reconnect via your member portal,” with a Reconnect PayPal button. Approving with PayPal again sets up auto-renew. This is a reconnection, not a card fix, so there’s no card-update link and no retry counter.

Whether a member reaches your org’s PayPal account for recurring charges also depends on PayPal approving that account for recurring payments. Until that approval, one-off PayPal payments work and recurring memberships collect manually. See Connect PayPal and configure your payment processor.