​

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

This table shows all fields that sync between WeGive and Salesforce for recurring donations (scheduled donations). 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
• Hard-coded - Built into the integration logic and cannot be changed

---

​

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)

The export happens automatically after the create or update action in WeGive.

​

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
• Sync Frequency: The integration checks for updated Recurring Donation records on a scheduled basis (frequency varies by integration configuration)
• Modified Field Tracking: Only Recurring Donation records with a LastModifiedDate newer than the last successful sync are pulled into WeGive

This means:

• Creating a new Recurring Donation in Salesforce will import it to WeGive on the next sync cycle
• Updating an existing Recurring Donation in Salesforce will trigger an import to WeGive on the next sync cycle
• The sync is based on Salesforce’s LastModifiedDate field, not individual field changes

---

​

Sync Process Overview

​

Recurring Donation-Level Synchronization

WeGive syncs scheduled donations at the Recurring Donation level in Salesforce, which is NPSP’s standard object for tracking ongoing giving commitments. Each scheduled donation in WeGive corresponds to a Recurring Donation in Salesforce, maintaining the complete recurring giving plan including donor information, donation amount, frequency, payment method, and status.

​

Pulling Data from Salesforce

When pulling data from Salesforce, WeGive queries Recurring Donation records based on the last modified date and any specific filtering criteria. The integration pulls comprehensive data from the Recurring Donation record, including all standard and custom fields that have been mapped. This data is used to create or update the corresponding WeGive ScheduledDonation record, maintaining all the necessary relationships to donors and campaigns. The import process includes special handling for installment frequency and period mappings, ensuring that recurring schedules are properly interpreted across both systems.

​

Pushing Data to Salesforce

When a ScheduledDonation record is created or updated in WeGive, the integration compiles a payload for the Salesforce Recurring Donation object. This payload includes all mapped fields and ensures that the Recurring Donation record is properly created or updated in Salesforce. The integration handles complex logic including:

• Amount Calculation: If donor opted to cover fees, includes both donation amount and fee amount
• Status Mapping: Automatically sets status to Active, Paused, or Closed based on the scheduled donation state
• Frequency Mapping: Converts WeGive frequency values to NPSP’s Installment Period and Installment Frequency fields
• Day of Month Extraction: Automatically extracts the day of month from the start date
• Payment Method Mapping: Maps WeGive payment types to NPSP payment method values
• Card/ACH Details: Populates last 4 digits for card or ACH payment methods

NPSP Installment Auto-Creation Prevention: The integration sets npsp__DisableFirstInstallment__c to true to prevent NPSP from automatically creating Opportunity records. This is critical because WeGive handles creating Opportunities as actual donations are processed, ensuring better control over donation record creation and maintaining accurate donor history.Standard Field Mappings

​

Picklist Values

​

npe03__Installment_Period__c (Installment Period)

The integration maps WeGive frequency to Salesforce Installment Period: Configuration: These mappings can be customized in your integration settings to match your Salesforce org’s Installment Period picklist values. The combination of Installment Period and Installment Frequency determines the exact recurring schedule. Example: “biweekly” = Installment Period: “Weekly” + Installment Frequency: “2” (every 2 weeks)

​

npsp__Status__c (Recurring Donation Status)

The integration automatically determines the status based on the scheduled donation state:

​

Configuration: Status mapping is hard-coded based on the scheduled donation’s state and cannot be customized. The status is automatically calculated based on:

• paused_at - If set, status = Paused
• deleted_at - If set, status = Closed
• ends_at - If in the past, status = Closed
• Otherwise, status = Active

---

​

npsp__PaymentMethod__c (Payment Method)

The integration maps WeGive payment types to Salesforce Payment Method values for recurring donations: Configuration: Payment method mappings can be customized in your integration settings to match your Salesforce org’s Payment Method picklist values. This uses the same mapping configuration as the Payment object.

---

​

Important Notes

​

Enhanced Recurring Donations Required

This integration requires NPSP’s Enhanced Recurring Donations to be enabled. Standard Recurring Donations are not supported. Enhanced Recurring Donations provide better scheduling, status tracking, and payment method management.

​

NPSP Configuration Requirements

For the integration to work properly, your NPSP settings must be configured as follows:

1. Enable Enhanced Recurring Donations - Must be enabled
2. Installment Opportunity Auto-Creation - Must be set to “Disable All Installments”
3. Next Donation Date Match Range - Must be set to NULL

These settings prevent NPSP from automatically creating Opportunity records, allowing WeGive to maintain control over when and how donation records are created.

​

Amount with Fee Coverage

If the donor has opted to cover processing fees (cover_fees enabled), the amount exported to Salesforce includes both the donation amount and the fee amount: (amount + fee_amount) / 100. Example: If a donor gives $100 monthly and covers a $3 processing fee:

• WeGive stores: amount = 10000 (cents), fee_amount = 300 (cents)
• Salesforce receives: npe03__Amount__c = $103.00 (donation + fee)

If fees are not covered:

• WeGive stores: amount = 10000 (cents), fee_amount = 300 (cents)
• Salesforce receives: npe03__Amount__c = $100.00 (donation amount only)

​

Installment Auto-Creation Disabled

The field npsp__DisableFirstInstallment__c is always set to true to prevent NPSP from automatically creating Opportunity records. This is essential because:

• WeGive handles creating Opportunities as actual donations are processed
• Prevents duplicate or premature Opportunity creation
• Maintains accurate donor giving history
• Gives the integration full control over the donation lifecycle

​

Day of Month Logic

The npsp__Day_of_Month__c field is automatically extracted from the start_date. Examples:

• If start_date is “2024-01-15”, day of month = “15”
• If start_date is “2024-03-01”, day of month = “1”
• If start_date is “2024-12-31”, day of month = “31”

This determines when monthly recurring donations will be processed each month.

​

Payment Method Mapping

The npsp__PaymentMethod__c field is populated based on the payment method type using the same mapping as the Payment object. Common mappings include:

• Credit/Debit Card → “Credit Card”
• Bank Account (ACH) → “ACH/EFT”
• PayPal → “PayPal”
• Other payment types are mapped according to your integration settings

​

Card vs ACH Last 4

The integration populates either card or ACH last 4 digits, never both:

• If payment method is a card: npsp__CardLast4__c is populated with last 4 digits
• If payment method is a bank account: npsp__ACH_Last_4__c is populated with last 4 digits
• For other payment methods: Both fields remain empty

This helps identify the payment instrument for reporting and donor service purposes.

​

Organization vs Contact

When exporting to Salesforce, the integration determines which donor relationship field to populate:

• For individual donors: npe03__Contact__c is populated with the donor’s Salesforce Contact ID
• For company donors: npe03__Organization__c is populated with the donor’s Salesforce Account ID

Only one of these fields will be populated for any given recurring donation.

​

Start Date vs Created Date

Two date fields serve different purposes:

• npsp__StartDate__c - When the recurring donation plan was created (uses created_at)
• npe03__Next_Payment_Date__c - When the next donation should be processed (uses start_date)

This distinction helps track both the commitment date and the payment schedule.

​

Frequency Combination

NPSP uses a combination of two fields to define recurring schedules:

• npe03__Installment_Period__c - The time unit (Daily, Weekly, Monthly, Yearly)
• npsp__InstallmentFrequency__c - How many of that unit between donations

Examples:

• Weekly + Frequency 1 = Every week
• Weekly + Frequency 2 = Every 2 weeks (biweekly)
• Monthly + Frequency 3 = Every 3 months (quarterly)
• Monthly + Frequency 6 = Every 6 months (semiannually)

---

​

Recurring Donation Matching & Create/Update Logic

When WeGive exports a scheduled donation to Salesforce, the integration uses the following logic:

​

Step 1: Check for Existing Salesforce Recurring Donation ID

The integration first checks if the WeGive scheduled donation already has a salesforce_id stored:

• If Salesforce Recurring Donation ID exists: The integration will UPDATE the existing Recurring Donation record in Salesforce
• If no Salesforce Recurring Donation ID exists: The integration creates a NEW Recurring Donation in Salesforce

​

Why This Matters

Each scheduled donation creates a unique Recurring Donation record. This approach ensures:

• Every recurring donation plan is tracked separately
• Updates modify the correct, linked Recurring Donation
• Status changes (active/paused/closed) are properly reflected in Salesforce
• Payment method and amount changes are accurately tracked

Important: Like Opportunities and Payments, Recurring Donations are never matched by attributes (only by stored Salesforce ID). If a scheduled donation loses its salesforce_id reference in WeGive, it will create a duplicate Recurring Donation in Salesforce on the next sync. Always maintain the Salesforce ID relationship for scheduled donations to prevent duplication.

---

​

Related Opportunity Creation

​

How Recurring Donations Create Opportunities

When a transaction is processed for a recurring donation in WeGive, the integration creates an associated Opportunity in Salesforce that is linked to the parent Recurring Donation. This follows NPSP’s model where:

• Recurring Donation = The ongoing commitment/schedule
• Opportunity = Each individual donation/installment

​

Opportunity Field Mappings for Recurring Donations

When an Opportunity is created from a recurring donation transaction, the following fields are set to link and identify it: Key Behaviors:

1. Type Field: The Type field is automatically set to “Recurring” for all Opportunities created from scheduled donations, distinguishing them from one-time gifts.
2. Recurring Donation Link: The npe03__Recurring_Donation__c field creates the parent-child relationship between the Recurring Donation and each installment Opportunity.
3. Matching Existing Opportunities: When a transaction is synced for a recurring donation, the integration first checks if an Opportunity already exists with:
   • Matching npe03__Recurring_Donation__c (links to the parent recurring donation)
   • StageName = 'Pledged' (indicating it’s a placeholder installment)
   If found, this existing Opportunity is updated. Otherwise, a new Opportunity is created.
4. Payment Creation: If uses_payments = true, the integration also creates a Payment record linked to the Opportunity, providing detailed payment transaction information.

​

Example Scenario

Initial Setup:

1. Donor sets up a $100/month recurring donation in WeGive
2. Recurring Donation record created in Salesforce with npsp__Status__c = 'Active'

Each Month:

1. Transaction processes in WeGive for $100
2. Integration creates/updates an Opportunity in Salesforce:
   • Amount = $100
   • Type = 'Recurring'
   • npe03__Recurring_Donation__c = [parent recurring donation ID]
   • StageName = 'Closed Won' (if successful)
3. If payments enabled, a Payment record is also created

Result:

• One Recurring Donation record tracking the overall commitment
• Multiple Opportunity records, one for each monthly installment
• Optional Payment records for detailed transaction information

This structure allows NPSP to properly roll up giving totals, track installment history, and maintain the relationship between the ongoing commitment and individual gifts.