Recurring Contributions

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 contribution_status_id of 'Pending' with a payment added when appropriate using 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 repeatcontribution call takes precedence for the fields

    • campaign_id
    • total_amount and financial_type_id IF the contribution has exactly one line item

  • Next in precedence is the data in the civicrm_contribution_recur record. This can, with supply the same fields plus is_test and 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 TemplateContribution indicates an intention to use it to manage the data copied in future any changes to the TemplateContribution will automatically result in a change to the RecurringContribution record. So, although the RecurringContribution record takes precedence it will hold the same data

  • Finally if there is no TemplateContribution then 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 RecurringContribution in the same way a real TemplateContribution was. 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 RecurContribution in this circumstance.