​

Recurring Donation (Scheduled Donations) - Field Mapping

Salesforce Object: npe03__Recurring_Donation__c
WeGive Model: ScheduledDonation

​

NPSP Requirements

Required NPSP Settings:

• Enable Enhanced Recurring Donations
• Installment Opportunity Auto-Creation: Disable All Installments
• Next Donation Date Match Range: NULL

---

​

How Recurring Donation Data Syncs

Direction:

• Import from Salesforce - Data imports from Salesforce into WeGive only
• Export to Salesforce - Data exports from WeGive to Salesforce only
• Both Ways - Data syncs in both directions

Mapping Types:

• Configurable - Can be customized via integration settings or mapping rules
• Configurable (mapping rule) - Reaches Salesforce only when a mapping rule for it exists
• Hard-coded - Built into the integration logic and cannot be changed

---

​

Sync Configuration

Recurring Donation pulls and pushes are controlled by the Pull recurring donations and Push recurring donations toggles in Sync Configuration. Related settings:

---

​

Sync Triggers

​

From WeGive to Salesforce (Export)

Recurring donation data is exported from WeGive to Salesforce when:

• Recurring Donation Created: A new scheduled donation is created in WeGive
• Recurring Donation Updated: An existing scheduled donation is modified in WeGive (e.g., amount changed, status changed, payment method updated, paused/resumed)

A recurring gift’s first installment may also push the plan inline if the plan has not yet received a Salesforce ID, so the Opportunity can be linked to it.

​

From Salesforce to WeGive (Import)

Recurring donation data is imported from Salesforce to WeGive based on:

• Last Modified Date: WeGive periodically polls Salesforce for Recurring Donation records that have been modified since the last sync
• Status filter: Only records with npsp__Status__c = 'Active' are pulled unless sync_all_recurring_donations is enabled
• Modified Field Tracking: Only records with a LastModifiedDate newer than the last successful sync are pulled into WeGive

​

Deleted Recurring Donations

When pull_deleted_scheduled_donations is enabled, Recurring Donations with IsDeleted = true in the sync window soft-delete the matching WeGive plan.

---

​

Sync Process Overview

​

Pulling Data from Salesforce

The base query reads Id, CreatedDate and the Organization Account’s Record Type name; all other fields come from your Recurring Donation mapping rules. When enable_fund_allocations is on, the plan’s npsp__Allocation__c children are fetched in the same query. The import then:

• Matches the WeGive plan by stored salesforce_id, creating a new plan if none exists
• For new plans only, resolves the donor from the mapped Contact (source.salesforce_id) and/or Account (source.salesforce_account_id). If the Account’s Record Type is not the household Record Type it is treated as an Organization Account and the company donor is used; otherwise the Contact is used. The record fails if no donor is found
• Resolves campaign and fund from mapped Salesforce IDs
• Resolves the WeGive frequency by matching the mapped period and frequency values against the frequency map
• Applies CreatedDate to created_at on create only
• Converts last_change_amount and campaign_change_amount from dollars to cents if mapped

​

Pushing Data to Salesforce

Before the plan is pushed, the donor is pushed if it has no Salesforce ID and the payment method is pushed as an accessory (a payment method failure does not block the plan). The payload then includes:

• Amount Calculation: If the donor opted to cover fees, the donation amount plus the fee amount
• Status Mapping: Active, Paused, or Closed based on the plan state
• Frequency Mapping: WeGive frequency converted to NPSP Installment Period and Installment Frequency
• Day of Month: Taken from the start date
• Payment Method: From the payment method name settings
• Card/ACH Last 4: Last four digits of the payment method
• Lifecycle timestamps: Managed-package DateTime fields for pause, cancellation, last failure and last sync

The same payload is used for create and update. NPSP Installment Auto-Creation Prevention: npsp__DisableFirstInstallment__c is always sent as true so NPSP does not create the first installment Opportunity. WeGive creates Opportunities as donations are processed.

​

Field Mappings

​

Values Available to Mapping Rules

In addition to the plan’s attributes and custom fields, export rules can map:

• status - WeGive’s own plan status vocabulary (Active, Paused, Cancelled), as opposed to the NPSP vocabulary written to npsp__Status__c
• ends_at - formatted Y-m-d
• last_change_amount, campaign_change_amount - change-history deltas in dollars
• source, fund, campaign, paymentMethod attributes

​

Picklist Values

​

npe03__Installment_Period__c and npsp__InstallmentFrequency__c

Each WeGive frequency maps to a period plus a numeric frequency through the integration’s frequency map. For example, “biweekly” is Installment Period “Weekly” with Installment Frequency 2, and “quarterly” is “Monthly” with 3. On import, the mapped period and frequency pair is looked up in the same map to recover the WeGive frequency; a pair that does not match leaves the frequency unset.

​

npsp__Status__c (Recurring Donation Status)

Closed takes precedence over Paused. This logic is hard-coded.

​

npsp__PaymentMethod__c (Payment Method)

Blank settings write nothing. There are no other built-in values. These are the same settings used for npe01__Payment_Method__c on Payments, so both objects carry the same vocabulary.

---

​

Important Notes

​

Enhanced Recurring Donations Required

This integration requires NPSP’s Enhanced Recurring Donations. Standard Recurring Donations are not supported.

​

Amount with Fee Coverage

If the donor has opted to cover processing fees, the exported amount is (amount + fee_amount) / 100. Example: A $100 monthly gift covering a $3 fee exports as npe03__Amount__c = 103.00; without fee coverage it exports as 100.00.

​

Day of Month and Start Date

Both npsp__Day_of_Month__c and npsp__StartDate__c are derived from the plan’s start_date. If start_date is empty the plan’s created_at is used, and if that is empty, the current date.

​

Card and ACH Last 4

npsp__CardLast4__c and npsp__ACH_Last_4__c are both populated with the payment method’s last four digits regardless of whether the payment method is a card or a bank account. They are empty when the plan has no payment method.

​

Organization vs Contact

Default behavior:

• npe03__Contact__c is always set to the donor’s Contact ID (salesforce_id), for individuals and companies alike
• npe03__Organization__c is set to the donor’s Account ID only for company donors

With push_rd_household_for_individuals enabled:

• Individual donors also get npe03__Organization__c set to their household Account ID, so NPSP can roll up household totals
• Company donors get npe03__Contact__c set to the company’s primary individual (the donor’s linked primary individual, or the Account’s npe01__One2OneContact__c looked up from Salesforce)

On import, donor resolution uses the mapped Contact and Account IDs together with the Account’s Record Type (see Pulling Data from Salesforce).

​

Create vs Update

The same payload is sent on create and update. There are no create-only fields on the Recurring Donation.

---

​

Recurring Donation Matching & Create/Update Logic

​

Step 1: Check for Existing Salesforce Recurring Donation ID

• If salesforce_id exists: UPDATE the existing Recurring Donation
• If not: acquire a per-plan lock and INSERT a new Recurring Donation, then store its ID

​

Step 2: Allocations

When enable_fund_allocations is on AND push_fund_allocations is on, the plan’s fund allocations are synced to npsp__Allocation__c records on the Recurring Donation after the push (see the GAU & Allocation page). When either is off, no allocation is created for the Recurring Donation.

---

​

Related Opportunity Creation

​

How Recurring Donations Create Opportunities

When a transaction is processed for a recurring donation in WeGive, the integration creates an Opportunity linked to the parent Recurring Donation:

• Recurring Donation = the ongoing commitment/schedule
• Opportunity = each individual donation/installment

​

Opportunity Field Mappings for Recurring Donations

Key Behaviors:

1. Plan pushed first: If the plan has no Salesforce ID when its installment pushes, the plan is pushed inline first.
2. Matching existing Opportunities: Before creating a new Opportunity, the integration looks for an Opportunity on the same Recurring Donation with StageName = 'Pledged' (the literal NPSP value, regardless of your stage_pending setting). If found, it is adopted and updated instead. With uses_payments, an existing Payment on that Opportunity is adopted too.
3. Payment creation: If uses_payments is enabled, a Payment is created or updated on the Opportunity.
4. Allocations on installments: NPSP copies the Recurring Donation’s GAU Allocations onto each installment Opportunity. The integration adopts those records rather than creating its own, and never deletes them. See the GAU & Allocation page.

​

Example Scenario

1. Donor sets up a $100/month recurring donation in WeGive; a Recurring Donation is created with npsp__Status__c = 'Active'
2. Each month a transaction processes; the integration creates or updates an Opportunity with Type = 'Recurring', the configured success StageName, and npe03__Recurring_Donation__c pointing at the plan
3. If payments are enabled, a Payment record is also created

​

Related Documentation

• Data Mapping Overview - object index and cross-cutting data conventions
• Opportunity & Payment - installment Opportunities and Payments
• GAU & Allocation - fund allocations on Recurring Donations and installments

Verified against the integration source, September 2026.