Charitable Documentation

Learn how to make the most of Charitable with clear, step-by-step instructions.

Changing Recurring Donation Amounts and Billing Periods

Requires:

  • Charitable Pro 1.8.16+
  • Charitable Recurring Donations 2.1.0+

A donor’s situation changes. Maybe next month is tight and they want to drop their $50 monthly gift to $25, or a matching grant came through and they’d like to bump up their annual donation. Before Charitable Recurring 2.1, the only way to handle that was to cancel the subscription and ask the donor to start a new one, which loses the payment history and risks the gift never coming back.

Now you can update an active recurring donation’s amount and billing period directly from your WordPress admin, and the change syncs to Stripe automatically. The same subscription stays in place, so the payment history is preserved and the donor keeps their original start date.

You can apply a change immediately, or send the donor a secure approval link first. Every change is written to your audit log, and changes you make in the Stripe Dashboard sync back to Charitable on their own.

The Donation Actions box on a recurring donation with Update Subscription selected in the dropdown and the Update Subscription button below it

When you’d use it

  • A donor asks to change their amount – update it in seconds instead of cancel-and-resubscribe.
  • A donor wants to switch from monthly to annual (or any other period) – change the billing period in place.
  • A change needs the donor’s sign-off – send an approval email and let the donor confirm before anything happens at Stripe.
  • Someone edited the subscription in the Stripe Dashboard – Charitable picks up the new amount and period automatically.
  • You need a record of who changed what – every update lands in Charitable’s logs with the old value, new value, and who made it.

Finding it

Open the recurring donation you want to change:

WordPress Admin > Donations > Recurring Donations > (click the donation)

The Recurring Donations list in the Charitable menu, showing recurring donations with their status filters

In the Donation Actions box on the right, choose Update Subscription from the dropdown, then click the Update Subscription button.

The donation must use the Stripe gateway and be in Active status. Paused, cancelled, completed, and pending subscriptions can’t be edited, which keeps the donor from being surprised by an unexpected charge.

Updating a subscription

The Update Subscription window shows the current subscription at the top, then the fields you can change.

The Update Subscription window showing the current subscription, the New Amount field, the New Billing Period dropdown, the Subscription Term and Update Mode options, and the donor notification checkbox

1. Set the new amount and/or period

  • New Amount – enter any value from 1.00 up to (in theory) 999999.99. Leave it unchanged to keep the current amount.
  • New Billing Period – choose from daily, weekly, monthly, quarterly, semiannually, or yearly. Leave it on the current period to keep it.

You can change one or both. The change takes effect on the donor’s next billing date; their current cycle finishes normally, and no proration is applied.

2. Choose how the change is applied

  • Apply immediately – the change is sent to Stripe right away.
  • Request donor approval – a pending change is stored and the donor receives an email with secure approve and deny links. Nothing changes at Stripe until they approve.
The Update Subscription window with a new amount of 40.00, a Quarterly billing period and Request donor approval selected

3. Decide whether to notify the donor

The Notify donor of this change checkbox is on by default. When checked, the donor receives a “Subscription Updated” email with the old and new amount or period. Uncheck it for back-office adjustments the donor doesn’t need to hear about.

When you click Update Subscription, you’ll see a success message and the donation total updates on the page.

The donor approval workflow

When you choose Request donor approval, the donor gets an email with two links: one to approve the change and one to deny it.

The Subscription Change Request email a donor receives, with an Approve this change link and a link to decline the change

A few things worth knowing about how the approval links work:

  • Secure and donation-specific. Each link carries a signed token tied to that exact donation. A link for one donation can’t be used on another.
  • They expire. Approval links are valid for 7 days. After that, the link stops working and you’d need to re-issue the request.
  • One use only. Once the donor approves or denies, the link is spent. Clicking it again does nothing.
  • A new request replaces an old one. If you issue a second change while one is still pending, the newer request supersedes the older one and the old link stops working.

If the donor clicks Approve, the change is pushed to Stripe and the donation updates. If they click Deny, the subscription stays exactly as it was and the pending change is cleared.

Changes made in the Stripe Dashboard

If you (or a teammate) edit a subscription’s amount or billing period directly in the Stripe Dashboard, Charitable notices and updates the local donation to match. This happens through the Stripe webhook you already have configured, so there’s nothing extra to set up. It means the donation record in WordPress stays accurate no matter where the edit was made.

Reading the audit log

Every subscription change is recorded in your Charitable logs, whether it came from an admin update, a donor approval, or the Stripe Dashboard.

WordPress Admin » Charitable » Tools » Logs

Each entry records the old value, the new value, who made the change, and when. You can filter by donation ID to see the full history of a single subscription.

The donor notification email

By default, donors receive a “Subscription Updated” email after a successful change, laying out what changed. You can customize or disable it from:

WordPress Admin » Charitable » Settings » Emails

The Charitable Emails settings listing the Subscription Updated and Subscription Change Request donor emails

Two emails relate to this feature:

  • Subscription Updated – sent to the donor after a change is applied. On by default.
  • Subscription Change Request – the approval-request email, sent when you choose “Request donor approval.”

Click either email to edit its subject, headline, and body, or to turn it off.

Tips

  • Use Request donor approval for any change a donor didn’t explicitly ask for, so they always have the final say.
  • The donation’s Active status is required. If the Update Subscription option is missing or disabled, check the subscription status first.
  • Changes take effect on the next billing cycle, not immediately, so the donor is never double-charged in the current period.

Developer reference

The full update path is built on hooks, so you can intercept, extend, or react to subscription changes.

Filters

FilterDefaultPurpose
charitable_process_subscription_update_stripearray( 'success' => false, 'message' => ... )Implemented by Charitable Pro 1.8.16+. Receives the recurring donation and the proposed changes, pushes them to Stripe, and returns a result array. Both the admin update endpoint and the donor approval handler call it.
charitable_recurring_confirmation_page_colorsbrand colorsColors for the donor-facing approve/deny confirmation page.
charitable_recurring_confirmation_page_headingper-action headingThe heading shown on the confirmation page.
charitable_recurring_confirmation_page_messageper-action messageThe body message on the confirmation page.
charitable_recurring_confirmation_page_buttonreturn-home buttonThe button shown on the confirmation page.
charitable_recurring_confirmation_page_htmlemptyReturn custom HTML to replace the entire confirmation page.

Actions

ActionArgumentsWhen it fires
charitable_recurring_subscription_updated$donation, $changes, $old_valuesAfter a successful update. Triggers the “Subscription Updated” donor email when that email is enabled.
charitable_recurring_subscription_change_requested$donation, $pending_data, $raw_tokenWhen an admin requests donor approval. Triggers the approval-request email.
charitable_stripe_subscription_details_changed$subscription, $stripe_objectFired by Pro’s webhook processor on a Stripe customer.subscription.updated event. The reverse-sync listener reads the new amount and period off the Stripe object.

Helper functions and classes

  • charitable_recurring_update_local_subscription( $donation, $changes ) – updates local meta only. Handles single-campaign and multi-campaign proportional distribution of a new amount.
  • Charitable_Recurring_Subscription_Change_Handler::process_approval() – handles the donor’s approve click (?donation_id=X&token=Y&action=approve).
  • Charitable_Recurring_Subscription_Change_Handler::process_denial() – handles the deny path.
  • Charitable_Recurring_Subscription_Change_Handler::cleanup_expired_pending_changes() – removes expired pending-change records (runs on a scheduled event).
  • Charitable_Gateway_Stripe_AM::$period_map – static array mapping each Charitable period to a Stripe interval and interval_count.
  • Charitable_Gateway_Stripe_AM::update_subscription( $result, $donation, $changes ) – the method behind the filter; mints a Stripe Plan for the new args and swaps the subscription’s item to it with proration disabled.

Period mapping

The amount and period you set map to Stripe’s billing model like this:

Charitable periodStripe intervalinterval_count
dayday1
weekweek1
monthmonth1
quartermonth3
semiannualmonth6
yearyear1

Approval token

The approval link uses an HMAC-SHA256 token bound to the donation ID, the time the change was proposed, and a one-time 32-character secret. Tokens expire after 7 days. A repeated-attempt counter is stored in the charitable_sub_token_attempts_{donation_id} transient, and the pending-change record is deleted on approve or deny so a link can’t be replayed.

Customization examples

Add a custom log line whenever a subscription is updated:

add_action( 'charitable_recurring_subscription_updated', function ( $donation, $changes, $old_values ) {
    error_log( sprintf(
        'Subscription #%d updated: %s',
        $donation->ID,
        wp_json_encode( $changes )
    ) );
}, 10, 3 );

Notify your team in Slack when a donor approval is requested:

add_action( 'charitable_recurring_subscription_change_requested', function ( $donation, $pending_data, $raw_token ) {
    my_slack_notify( sprintf(
        'Approval requested for recurring donation #%d',
        $donation->ID
    ) );
}, 10, 3 );

Brand the donor confirmation page:

add_filter( 'charitable_recurring_confirmation_page_colors', function ( $colors ) {
    $colors['primary'] = '#16a34a';
    return $colors;
} );

Related

Still have questions? We’re here to help!

Last Modified:

What's New In Charitable

View The Latest Updates
🔔 Subscribe to get our latest updates
📧 Subscribe to Emails

Email Subscription

Join our Newsletter

We won’t spam you. We only send an email when we think it will genuinely help you. Unsubscribe at any time!

Donations New

👥 Introducing Donor Merging: Two Records, One Supporter!

Somewhere in your donor list is a supporter who appears twice, because they gave from a work address one year and a personal one the next. Every donation is still recorded and every receipt still went out, but a loyal supporter who has given for years can look like two people who gave half as much. From the Charitable Pro plugin 1.8.19.1 you can find those records and merge them from the Donors screen. Why this is important:

  • 🔍 A Find Duplicates link where you already work: Head to Charitable » Donors and it sits next to Filter and Export, then tells you how many groups of possible duplicates it found.
  • 🧩 Grouped by name, not by email: Charitable compares the first and last name together and ignores capital letters, spacing and punctuation, which is what catches the same person under two different addresses.
  • 📊 A preview before anything changes: Each group shows every record with its email address, its donation count and its lifetime total, and the preview shows you the combined totals and the email that will be added.
  • ↩️ Every merge can be undone: Nothing is merged until you choose to merge it, and you can reverse any merge afterwards, so a wrong guess costs you nothing.
  • 📥 Built for the week after an import: Moving donors over from another plugin is where most duplicates come from, and it is also when they are hardest to spot, because every record is new to you.

Check out our announcement here.

ambassadors New

🔑 Introducing Passwordless Fundraisers: Sign Up With Just an Email!

Supporters arrive wanting to help, and then the form asks them to invent a password for a website they may only visit twice. A lot of them stop right there. Passwordless Fundraiser Accounts, new in Charitable Ambassadors 3.5.0, let a supporter start a peer to peer fundraiser with nothing but an email address. Why this is important:

  • 🔑 No password step to lose them at: Switch it on in Charitable » Ambassadors » Templates » Submit Form and the create-fundraiser form asks only for a name, an email address and a page title.
  • 👤 Still a real WordPress account: One click in one email confirms the address, signs them in and creates the account, so they can come back later to edit their story, change their photo and see who has donated.
  • 🎚️ Your call on every campaign: Each peer to peer campaign can follow the site default or override it, which matters when a campaign pays fundraisers through Stripe Connect and those people do need a password.
  • 📋 See who has not clicked yet: The Charitable » Ambassadors » Directory » Awaiting Sign-In tab lists everyone still waiting, with the campaign they joined and a Resend button, so a typo or a spam folder is something you can spot and fix.
  • 🛡️ Links a scanner cannot use up: Opening the link only shows a page, and your fundraiser is signed in when they press the button on it, so corporate email scanners never burn the link. Each one works once, expires on its own and is stored only as a hash.

Check out our announcement here.

ambassadors New

🏃 Introducing Activity: Show Progress on More Than Money!

Most peer-to-peer fundraisers are about more than the money. A read-a-thon is about minutes read, a walkathon is about miles walked, and a food drive is about meals packed. Activity for Charitable Ambassadors lets your fundraisers show that effort right beside the dollars they raise. Why this is important:

  • 🎯 Progress on what you actually count: A progress bar shows each thing you count against its own target, sitting right beside the money raised.
  • 🏅 Milestones for the yes or no things: A milestone badge marks the efforts that are simply done or not done, with no number to chase.
  • ✍️ Fundraisers log their own numbers: Your supporters enter their totals from their own pages, so the effort stops living in a spreadsheet, a comment, or nowhere at all.
  • 🤖 Some numbers count themselves: An AUTOMATIC tag appears wherever the site worked the figure out from completed donations, so you can see at a glance what nobody typed in.
  • 🧩 Set it up once, use it anywhere: You decide what gets counted one time, then choose which campaigns count it. Available now in Charitable Ambassadors 3.4.7, with no new plugin and no developer.

Check out our announcement here.

ambassadors New

🖨️ Introducing Fliers and Posters: Raise Money Away From the Screen!

A lot of peer-to-peer fundraising happens away from a screen: at the finish line of a 5K, on a school noticeboard, in an office kitchen. Charitable Ambassadors 3.4.7 adds 2 printables, a fundraiser flier carrying each fundraiser’s own story and QR code, and a recruitment poster that signs new fundraisers up. Both open as a normal web page and print straight from the browser. Why this is important:

  • 🏁 A flier for every fundraiser: Each one carries that fundraiser’s own photo, story and goal, with a QR code that opens their page rather than your main campaign.
  • 📌 A poster that recruits: It shows “Now Recruiting” above your campaign name with a large QR code that opens your sign-up form, so someone can start fundraising without waiting on a link from you.
  • 🪄 No design tool needed: Both printables render as a normal web page and print from the browser, with no PDF plugin and no designer.
  • 📄 2 flier layouts: Hand out carries the full story for giving to friends and family, and Post up carries a short hook with 5 tear-off tabs for a noticeboard.
  • 🛡️ Off until you switch it on: Fliers stay off after the update until you enable them under Charitable » Ambassadors » Other » Fliers, and only the owner or an administrator can open one.

Check out our announcement here.

Improvement Payments

💸 Introducing Tiered Rates for Fee Relief: Match the Ask to the Gift!

Fee Relief asks your donors one short question at checkout: would you like to cover the processing fee on this gift? Until now that question used a single rate for every donation on a gateway, so a $10 gift and a $500 gift were asked for the same percentage. Fee Relief 1.3.0 lets you set as many donation bands as you like, each carrying its own rate. Why this is important:

  • 🪙 Gentler on small gifts: A fixed transaction cost is a far bigger share of a $10 donation than a $500 one, so bands let you ask for less at the bottom.
  • 🎚️ As many bands as you need: Each band carries its own percentage and its own fixed amount, and the top band runs on with no upper limit.
  • 🛑 An optional ceiling: A Maximum fee field stops any donor being asked for more than a number you choose, however large the gift.
  • 🔌 Set per payment gateway: Stripe can run on four bands while Windcave and Payfast stay on a single rate, because bands belong to a gateway and not to your whole site.
  • 🛡️ Nothing changes until you say so: Your current rates stay exactly as they are until you switch Use Tiered Rates on under Charitable » Settings » Advanced » Fee Relief.

Check out our announcement here.