Update Recurring Contributions
Bulk-update your Recurring Contributions, e.g. for membership price increases.
Summary of how it works
-
You find Recurring Contributions that you wish to update, and provide a reason (e.g. "membership price hike") and the new amount. A Search Kit form and processing task are provided for this purpose at Contributions » Find Recurring Contributions to change
-
Activities are created to record details of the planned changes.
-
Background (cron) processing attempts the updates and updates the activities, leaving them with status either Completed (success) or Cancelled (failed). The activity details field records a log for full visibility on what happened.
Note that for this to work you need support from the payment processor in question. It has been written for GoCardless but designed to theoretically work with any payment processor but you should check with the maintainers and test. In general, if you see an Edit link for a Recurring Contribution that lets you change the amount, then it's likely to work (but you should test...).
The extension is licensed under AGPL-3.0.
Requirements
- PHP v7.4+
- CiviCRM 5.47
- Form Builder (core extension)
- Search Kit (core extension)
Usage
Finding the recurring contributions to update
Go to Contributions » Find Recurring Contributions to update to select a batch of Recurring Contributions to work with.
It makes sense to be as specific as you can here. Almost definitely you’ll want to include an amount filter. And you probably want to only try to change In Progress recurring contributions.
Then from the actions drop-down, choose Change Recurring Contribution subscriptions.
You can then specify a reason (this becomes the subject of the activity) and the new amount.
Once you press Queue changes activities are created. Activities are created with status Scheduled, and with a date that is 30 minutes from now. This gives you half an hour to cancel the operation if you made a mistake! (You can cancel changes simply by deleting the activities. Using the changes monitor form is an easy way to do that.)
Monitoring changes
As changes are just activities, you can look at them in any way you like. However a page at Contributions » Monitor Recurring Contribution changes is provided to list them in a useful way.
If you delete an activity before the background task gets to processing it, it will no longer be processed. (There's a bulk delete option from the Monitor page - take care!)
Hopefully your changes are all successful, but they may fail for a host of reasons. In these cases you should review the failed ones (activity status Cancelled) to see what happened and what action you need to take next.
How to increase Membership prices?
Take a particular membership and deal with that, then move on to other membership types in separate batches later. If multiple payment processors are in use, you probably want to do these batch at a time.
First, update the membership prices in the normal way - this will affect new signups (and renewals that are paid with one-off methods).
Then use this tool to find the relevant recurring contributions and queue up the changes. If you have two memberships using the same financial type and the same amounts etc, then you might have difficulty identifying which recurring contributions to select. Future improvements to the Search Kit/Form Builder form could be warranted here.
Can I do it for a single Recurring Contribution?
Yes, but you don’t need this extension for that, just find the Recurring Contribution and click Edit to provide a new amount.
Development notes
Q. Are there tests?
A. Yes there is reasonable test coverage. Anyone wishing to develop this should be running the tests before committing/PR-ing, and should be adding tests for their new features.
Q. What happens with template contributions?
A. A template contribution joined to the selected Recurring Contribution will be updated, including a single Line Item.
Warning: If you have template contributions with multiple line items, it will fail in a nasty way: the Recurring Contribution amount will be updated; the template Contribution total_amount will be updated, but the line items will not. As such the line items will no longer add up to the total. This could be improved in future.
Q. The queue service has received a lot of attention recently and could be good for things like this, why have you used activities?
A. Visibility and control. The queue service would be nice but at present there is no visibility; you can't see what's done and what's to-do. Since we're talking about individuals (typically) giving money, the visibility of what exactly is going on around that is very important. A staff person in a fundraiser/membership role must be able to easily see and control what's going on at any point, including to-do, successes, failures.
Q. What about locking?
A. Yes, the cost of visibility is that it is accepted that someone could feasibly change the activity record at the same time as the background queue does. But admins should only need to make a change to these activities if something has gone very wrong - oops, I put £100 instead of £10! In those situations they can (a) disable the Scheduled Job (if they have permission), and/or (b) delete all Scheduled activities of this type. But of course with something like this you need planning, patience and careful oversight.