Update Recurring Contributions
Bulk-update your Recurring Contributions, e.g. for membership price increases, from the back end, and offer supporters a way to update their own giving through your own website.
Summary of how the bulk update 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...).
Summary of how the self-service update works.
This is an Inlay type called Update Giving that you can embed any website.
!!! warning This is quite specific; it's only currently of use to people using GoCardless.
Once you have the inlay placed, you can use CiviMail (etc.) to send people a special link to your website:
https://example.com/some/page#{contact.checksum}~cid={contact.contact_id}Where https://example.com/some/page is the URL to the page you put the inlay on.
It will load their details and present their In Progress recurring contributions, and ask them for a new amount.
If there is a single GoCardless recurring contribution, then when they hit submit we will attempt to change the subscription at GoCardless, and thank them if it worked. In all other situations, they're sent to a new donation landing page (on which you could put a Payment Inlay that sets up a new recurring payment). In this case you need to monitor new recurring signups and immediately inspect the donor's record to cancel the other payments - or they'll end up paying twice! The reason for this is that not all payment processors can change the subscription amounts. And if there are multiple, event multiple GoCardless ones, it's too much logic to figure out which to update, which to cancel etc.
The code fires hooks at various stages, so (for example) if you have 'regular' contributions that are not attached to a ContributionRecur entity, you could add those to the summary list.
Requirements
- PHP v7.4+ (8 might be required, can't remember...You should definitely be on 8 now.)
- CiviCRM 5.64
- Form Builder (core extension)
- Search Kit (core extension)
The extension is licensed under AGPL-3.0.
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.