Recurring contributions record an intent to make ongoing contributions.
Core CiviCRM supports recurring contributions in conjunction with a payment processor. The recurring contribution record describes the frequency amount and currency along with relevant dates and the status.
Depending on the payment processor the processing of recurring contributions may be managed by the processor, with CiviCRM being notified as payments take place, or by CiviCRM with a scheduled job initiating payments based on the information in the recurring contribution table.
When a recurring payment is recorded the
Contribution.repeattransaction APIv3 is used
(ideally with a
'Pending' with a payment added when appropriate
Payment.create APIv3). This api takes charge of creating a new contribution, combining
incoming data with one or more of the
ContributionRecur record, the
Template Contribution or
the most recent successful contribution. The data copied over can include line items, custom data,
soft credits etc.
If values conflict between these sources the precedence is as follows
Data being passed into the
repeatcontributioncall takes precedence for the fields
- total_amount and financial_type_id IF the contribution has exactly one line item
Next in precedence is the data in the
civicrm_contribution_recurrecord. This can, with supply the same fields plus
is_testand is subject to the one line item limitation
Next is the
TemplateContribution. This is an contribution that may be created by code or when a user edits the recurring contribution in the UI. This can hold any data that a normal contribution can and exists in the database as a hidden contribution (
is_template= 1). Because the existence of a
TemplateContributionindicates an intention to use it to manage the data copied in future any changes to the
TemplateContributionwill automatically result in a change to the
RecurringContributionrecord. So, although the
RecurringContributionrecord takes precedence it will hold the same data
Finally if there is no
TemplateContributionthen the most recent contribution in the series will be used to provide the relevant information as a pseudo-
TemplateContribution. For a period leading up to the release of CiviCRM version 5.61 this was synced to update the
RecurringContributionin the same way a real
TemplateContributionwas. However, this is only desirable behaviours for some processors / sites because there are cases where a contribution amount may be edited that do not represent a change in the intention for future payments. For example a partial refund or an extra payment of an ad hoc amount is sometimes possible, processor dependent. From 5.61 onwards you should install the Recur future amounts extension if you want this behaviour. Over time it is expected to become obsolete as code that becomes aware of a change in intent should alter the
RecurContributionin this circumstance.