Recurring donations

This guide explains how recurring donations work in Gratora. You will learn about the subscription lifecycle, available frequencies, what the admin shows you, and how donors manage their own plans.

How recurring donations work

Recurring donations through Stripe follow a two-step process. The first donation is collected immediately, and then a subscription is created for future payments.

PayPal works the other way around. A PayPal subscription can only be opened against a billing plan, so Gratora creates one for the amount, currency, and interval the donor chose, and the first payment comes through that subscription rather than a separate charge. Either way, every payment lands in Gratora as its own donation attached to the plan.

PayPal offers a recurring option only once you have saved a webhook id for the credentials in use. Without one, PayPal cannot verify the events that report the subscription’s payments, so Gratora offers PayPal for one-time donations only. Saving the webhook id in the PayPal card turns recurring on.

First donation and subscription creation

When a donor sets up a recurring donation through Stripe, the following steps happen:

1. Gratora creates a PaymentIntent with setup_future_usage to collect the first payment and save the payment method.
2. The donor completes the first payment.
3. Gratora creates a Stripe Customer, Price, and Subscription for the donor.
4. The billing_cycle_anchor is set one interval ahead of the first payment date.
5. Future renewals are handled automatically by Stripe.

This approach ensures the donor is charged immediately for the first donation rather than waiting for the subscription billing cycle to begin.

What happens on renewal

When a Stripe renewal is due, Stripe generates an invoice and attempts to charge the donor’s saved payment method. Gratora receives an invoice.payment_succeeded webhook event and records a new donation linked to the recurring plan.

A PayPal subscription charges on its own schedule and reports each payment with a PAYMENT.SALE.COMPLETED event. Gratora records that as a new donation on the plan as well, and moves the next payment date on by one interval.

Each renewal donation is tracked with its own reference number and appears in the donor’s donation history.

Available frequencies

Gratora supports the following recurring frequencies:

Recurring plan details

Each recurring plan tracks the following information:

• Donor and associated form, campaign, and fund
• Gateway subscription reference
• Donation amount
• Interval (day, week, month, or year) and interval count
• Status
• Lifecycle timestamps (created, started, current period, next payment, resume date, last payment, canceled)
• Total number of payments made
• Total amount paid
• Number of failed renewals

Plan statuses

A recurring plan can have one of six statuses:

• Active: the plan is running and renewals are being processed
• Pending: the gateway has not started the subscription yet
• Past due: the gateway has stopped collecting after a declined renewal
• Paused: the plan is temporarily stopped and no renewals will be attempted
• Canceled: the plan has been permanently stopped
• Expired: the gateway let the subscription run out

Canceled and expired plans are finished, and accept no further changes.

Viewing plans in the admin

Open Fundraising, then Donors, open a donor, and go to the Recurring tab. The table lists each of their plans with the gateway and subscription reference, the amount and interval, the status, the next charge date, how many renewals have failed, and the lifetime total paid. The Subscriptions screen shows the same plans across every donor.

You can act on a plan from either screen: pause, resume, skip the next charge, change the amount, change the schedule, or cancel. Retrying a payment sits outside that menu and is offered on a plan that owes a renewal, where the gateway takes the instruction: Stripe does, PayPal keeps its own retry schedule and the row says so. Each action asks whether to tell the donor, and it is on by default. Donors can make the same changes themselves in the donor portal, and the donor page has a “Create a sign-in link” button so you can send someone straight into theirs.

Failed renewals

When a renewal payment fails, on either gateway, the plan’s failed-renewal counter goes up and the failure is recorded in the donor’s activity log. This typically happens when a donor’s payment method has expired or has insufficient funds. Gratora does not retry the charge itself: retries are the gateway’s job.

Gratora emails the donor the first time a renewal on a plan is declined. Later failures on the same plan do not send another email, so a card that keeps declining does not turn into a run of identical messages.

When the gateway reports that it has stopped collecting, the plan moves to past due: Stripe when the subscription goes past due or unpaid, PayPal when it suspends the subscription. A suspension that follows a pause or a skipped charge is the instruction Gratora sent coming back, so it leaves the plan as it is.

If Stripe eventually gives up and cancels the subscription at its end, Gratora mirrors that: the plan moves to canceled and the donor gets the cancellation email. A PayPal subscription that PayPal cancels or lets expire is mirrored the same way.

You can see the count in the Health column on the donor’s Recurring tab. Donors can replace the payment method on a plan themselves from the donor portal, which is the fix for an expired card. See “How donors manage their own plans” below.

How donors manage their own plans

Donors can manage their recurring plans through the donor portal without contacting your organization. On the Recurring tab, “Manage” opens the actions for a plan:

• Pause it for 1, 3, 6, or 12 months, after which it restarts on its own
• Skip the next charge, which pushes the next payment out by one interval
• Change the donation amount, which takes effect on the next renewal
• Change how often the donation is charged
• Update the payment method the plan is charged to
• Cancel the donation

A paused plan also shows a “Resume” button, which restarts it immediately.

Pause, skip, resume, and cancel behave the same on Stripe and PayPal: Gratora makes the matching call on the subscription, so the gateway and Gratora agree on the change straight away.

Changing the amount on Stripe takes effect straight away: Gratora puts a new price on the subscription with proration off, so the donor is charged the new amount from the next renewal and nothing is charged mid-cycle. PayPal will not apply a new amount until the donor approves it on PayPal’s own site, so the portal tells them nothing has changed yet and offers an “Approve the change” link. The plan keeps its old amount until PayPal reports the approval, and Gratora then writes the new one.

“Update payment method” shows only for gateways that can take a new one. Stripe donors get a card form inside the portal and the card goes straight to Stripe. PayPal does not let anyone else collect a funding source, so PayPal donors are sent to PayPal to change how they pay, and the donation carries on unchanged.

For more details on the donor portal, see the Donor portal documentation.