Nonprofit Success Pack: Best Practices Building Custom Recurring Donation Triggers with Composite API

Background: How Nonprofit Success Pack (NPSP) Creates Installment Opportunities

Enhanced Recurring Donations create installment Opportunities asynchronously. When a Recurring Donation is created or when certain monitored fields (referred to as key fields) change, NPSP evaluates the Recurring Donation and creates the appropriate installment Opportunity in a background job.

To avoid evaluating the same Recurring Donation more than once, NPSP tracks which Recurring Donations have already been queued for evaluation within the current operation. This safeguard works within a single transaction. The Composite API processes each sub-request as its own separate transaction, so the safeguard does not carry over from one sub-request to the next.

Why After-Insert Automation Causes Duplicate Opportunities

When a custom trigger on the Recurring Donation object updates a key field in an after-insert context, that update happens as a second, separate step after the Recurring Donation is first saved. NPSP treats the key field change as a reason to re-evaluate the Recurring Donation, so it starts a second background evaluation for the same record.

When records are created through the Composite API, the two evaluations run in separate transactions and can run at nearly the same time. Because of timing, neither evaluation sees the installment Opportunity that the other one is creating. Each evaluation concludes that the installment does not yet exist, and each one creates it. The result is two installment Opportunities (duplicate Pledged Opportunities) on the same Recurring Donation.

Which Recurring Donation Fields Are Key Fields

A key field is a field that drives installment Opportunity creation. When the value of a key field changes on an existing Recurring Donation, NPSP re-evaluates that Recurring Donation and may create a new installment Opportunity. A custom after-insert automation that updates any of the following fields during creation through the Composite API can therefore start the second evaluation that leads to duplicate Opportunities.

The standard NPSP key fields are listed below with the field label followed by its API name:

• Contact (API name npe03__Contact__c): the donor contact on the Recurring Donation

• Account or Organization (API name npe03__Organization__c): the donor account on the Recurring Donation

• Amount (API name npe03__Amount__c): the recurring donation amount

• Installment Period (API name npe03__Installment_Period__c): for example, Monthly or Yearly

• Number of Planned Installments (API name npe03__Installments__c)

• Installment Frequency (API name npsp__InstallmentFrequency__c)

• Start Date (API name npsp__StartDate__c)

• Day of Month (API name npsp__Day_of_Month__c)

• Status (API name npsp__Status__c)

• Payment Method (API name npsp__PaymentMethod__c)

• Campaign (API name npe03__Recurring_Donation_Campaign__c)

• End Date (API name npsp__EndDate__c)

Two additional types of key fields apply depending on how the org is configured:

• Currency (API name CurrencyIsoCode): In an org where Multi-Currency is enabled, the Currency field on the Recurring Donation is also a key field.

• Custom mapped fields: Any Recurring Donation field that is configured in the NPSP Recurring Donation field mappings (the settings that copy values from the Recurring Donation to the installment Opportunity) is also treated as a key field. These mapped fields vary from org to org, so review the org's field mappings to identify any additional key fields specific to that org.

A custom automation that needs to set or change any of these key fields during Recurring Donation creation should do so in a before-insert context, as described below.

NPSP Settings Governing Installment Opportunity Automation

Two specific fields within the NPSP Recurring Donations Settings (npe03__Recurring_Donations_Settings__c) define the timing and logic for installment Opportunity generation. Grasping these configurations is essential for optimizing integrations that programmatically create Recurring Donation records.

The primary field manages which installment records NPSP generates:

• Installment Opportunity Auto-Creation Option (API name npsp__InstallmentOppAutoCreateOption__c). This field utilizes three distinct values:

  • Always_Create_Next_Installment: The standard setting that triggers regular NPSP installment creation.

  • Disable_First_Installment: Skips the initial installment Opportunity while maintaining subsequent record generation.

  • Disable_All_Installments: Fully suppresses NPSP installment Opportunity creation.

Administrators can configure this field through the NPSP Settings tab, where it is presented as a picklist menu.

The secondary field determines the processing mode for the initial installment:

• Installment Opportunity First Create Mode (API name npsp__InstallmentOppFirstCreateMode__c). This field includes three operational modes:

• Synchronous (default): Generates the first installment record within the same transaction as the Recurring Donation.

• Asynchronous: Delegates first installment creation to a background job in a separate transaction.

• Asynchronous_When_Bulk: Processes small record sets synchronously but offloads to background jobs during bulk operations.

Note that the field Opportunity First Create Mode is absent from the standard NPSP Settings interface. To adjust this value, navigate to Setup, select Custom Settings, and edit the Recurring Donations Settings directly.

Best Practice: Set Recurring Donation Key Fields in a Before-Insert Context

Set the key field value on the Recurring Donation in a before-insert context so the value is part of the original record creation. Because the value is written during the initial save rather than as a later update, NPSP runs only one evaluation and creates exactly one installment Opportunity.

How to Apply This Best Practice

The general approach is to move the field assignment so it happens before the Recurring Donation is saved, rather than after.

For custom Apex triggers, assign the key field value directly on the records in the trigger's new-records collection during the before-insert event. Setting the value in place during before-insert does not require a separate update statement, so no second evaluation is queued.

For record-triggered Flows, use a Flow that runs before the record is saved (a fast field update, also called a before-save Flow) instead of a Flow that runs after the record is created. The before-save Flow sets the value as part of the original save.

For managed or third-party automation that you cannot modify, work with the package provider to confirm whether the field assignment can occur before insert. If the automation must run after insert, an alternative is to design the integration so that the dependent changes occur within the same transaction as the Recurring Donation creation, rather than relying on the Composite API to apply a separate after-insert update.

Real-Life Example

A nonprofit uses an external payment processor that sends donation data into Salesforce through the Composite API. The integration creates a Recurring Donation with the first installment disabled (by setting npe03__DisableFirstInstallment__c to true), creates a linked Closed Won Opportunity for the initial payment, and runs a custom trigger on the Recurring Donation that stamps an external identifier onto a field that NPSP treats as a key field.

When the custom trigger stamps the identifier in an after-insert context, NPSP creates two installment Opportunities for the next donation period instead of one. After the nonprofit changes the custom trigger to stamp the identifier in a before-insert context, NPSP creates a single installment Opportunity, and the duplicates no longer occur.

Verify the Change Safely

Test the change in a sandbox before deploying to production. Send a Composite API request that creates one Recurring Donation and its linked Opportunity, and confirm that exactly one installment Opportunity is created. Repeat the request several times, because timing-related behavior does not always appear on the first attempt. Monitor the org for a full day, including the nightly Recurring Donations batch job, to confirm there are no unexpected effects.

Scope and Limitations

This best practice addresses duplicate installment Opportunities caused by a custom after-insert automation that updates a Recurring Donation key field during creation through the Composite API.

A separate situation exists when two different Opportunities that belong to the same Recurring Donation are updated to Closed Won in two independent API transactions at nearly the same time. That situation is a separate concurrency consideration in the asynchronous installment-creation model and is not resolved by the before-insert trigger practice described here.