Pledge

Salesforce Object: wegive__Pledge__c (custom object)
WeGive Model: Pledge

Overview

This document describes how pledge data syncs between WeGive and Salesforce. Pledges represent commitments from donors to give a certain amount over a specified period, typically broken into installments.

Important Note: The pledge implementation varies by organization. This document covers the standard WeGive pledge object (wegive__Pledge__c). Some organizations may use custom implementations with different field names.

How Pledge 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
Hard-coded - Built into the integration logic and cannot be changed

Sync Triggers

From WeGive to Salesforce (Export)

Pledge data is exported from WeGive to Salesforce when:

Pledge Created: A new pledge is created in WeGive
Pledge Updated: An existing pledge is modified in WeGive (e.g., amount changed, dates updated, status changed)

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

From Salesforce to WeGive (Import)

Pledge data is imported from Salesforce to WeGive based on:

Last Modified Date: WeGive periodically polls Salesforce for Pledges that have been modified since the last sync
Sync Frequency: The integration checks for updated Pledges on a scheduled basis (frequency varies by integration configuration)
Modified Field Tracking: Only Pledges with a LastModifiedDate newer than the last successful sync are pulled into WeGive

This means:

Creating a new Pledge in Salesforce will import it to WeGive on the next sync cycle
Updating an existing Pledge 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

Pledge-Level Synchronization

WeGive syncs pledges at the Pledge object level in Salesforce, maintaining the commitment structure, payment schedules, and donor relationships. This includes pledge amounts, installment plans, payment tracking, and campaign associations.

Pulling Data from Salesforce

When pulling data from Salesforce, WeGive queries Pledges based on the last modified date and any specific filtering criteria. The integration pulls comprehensive data from the Pledge record, including all standard and custom fields that have been mapped.

The import process includes:

Donor Linking: Links the pledge to the appropriate donor (Contact or Account) in WeGive
Campaign Association: Associates the pledge with a campaign if specified
Fund Assignment: Links to a fund/designation if applicable
Installment Configuration: Sets up the payment schedule based on installment frequency and period
Status Tracking: Maintains the current status and payment progress

Pushing Data to Salesforce

When a Pledge is created or updated in WeGive, the integration compiles a payload for the Salesforce Pledge object. This payload includes all mapped fields and ensures that the Pledge record is properly created or updated in Salesforce.

Prerequisites for Creating Pledges: Before creating a pledge in Salesforce, the integration ensures:

Donor exists in Salesforce: The associated donor must have a Salesforce ID (Contact or Account)
Campaign exists (if applicable): If the pledge is associated with a campaign, that campaign must have a Salesforce ID
Fund exists (if applicable): If the pledge is designated to a fund, that fund must have a Salesforce ID

The integration will automatically push these related records if they don’t have Salesforce IDs yet.

Standard Field Mappings

Salesforce Field	WeGive Field	WeGive API Field	Direction	Type	Notes
Id	Salesforce ID	salesforce_id	Import from Salesforce	Hard-coded	Salesforce’s unique identifier for this pledge
wegive__Contact__c	Donor Salesforce ID	donor.salesforce_id	Both Ways	Hard-coded	Links to Contact (for individual donors)
wegive__Account__c	Donor Salesforce Account ID	donor.salesforce_account_id	Both Ways	Hard-coded	Links to Account (for company donors)
wegive__Campaign__c	Campaign Salesforce ID	campaign.salesforce_id	Both Ways	Hard-coded	Links to associated Campaign
wegive__Amount__c	Total Amount	total_amount	Both Ways	Hard-coded	Total pledge amount in dollars (WeGive stores in cents)
wegive__Start_Date__c	Start Date	start_date	Both Ways	Hard-coded	Date the pledge period begins
wegive__End_Date__c	End Date	end_date	Both Ways	Hard-coded	Date the pledge period ends
wegive__Next_Installment_Date__c	Next Installment Date	next_installment_date	Both Ways	Hard-coded	Date of the next expected payment
wegive__Installment_Period__c	Installment Frequency	installment_frequency	Both Ways	Hard-coded	Payment schedule (1, 4, 8, or ‘monthly’)
wegive__Description__c	Description	description	Both Ways	Hard-coded	Notes or description of the pledge
wegive__Is_Hidden__c	Hidden Status	is_hidden	Both Ways	Hard-coded	Whether the pledge is hidden from reporting
Name	Pledge Name	(auto-generated)	Import from Salesforce	Hard-coded	Display name for the pledge
CreatedDate	Created At	created_at	Import from Salesforce	Hard-coded	When the pledge was created

Important Notes

Donor Association

Pledges in WeGive must be associated with a donor. The integration handles both individual and company donors:

For Individual Donors:

Links via wegive__Contact__c field to the Contact’s Salesforce ID
The donor must have a salesforce_id in WeGive

For Company Donors:

Links via wegive__Account__c field to the Account’s Salesforce ID
The donor must have a salesforce_account_id in WeGive

On import, the integration searches for the donor using either the Contact ID or Account ID and throws an exception if no matching donor is found.

Installment Frequency Mapping

The integration maps between WeGive’s installment frequency values and Salesforce’s picklist values:

WeGive Value	Salesforce Value
1	”1 Payment”
4	”4 Payments”
8	”8 Payments”
monthly	”Monthly”
`transaction_id`	`transaction_id`

Campaign and Fund Linking

Campaign: If the pledge is associated with a campaign, the campaign must exist in Salesforce with a salesforce_id
Fund: If the pledge is designated to a fund, the fund must exist in Salesforce with a salesforce_id
The integration will automatically push these related records if needed before creating the pledge

Date Formatting

All dates are formatted as Y-m-d (e.g., “2025-01-15”) when syncing to Salesforce and are adjusted to the organization’s timezone.

Number of Installments

The number_of_installments field is set to 0 if not specified. This field tracks the planned number of payments for the pledge.

Required Fields

For WeGive to Salesforce:

Donor (either Contact or Account)
Total Amount (wegive__Amount__c)
Start Date (wegive__Start_Date__c)

For Salesforce to WeGive:

Donor reference (either wegive__Contact__c or wegive__Account__c)
Amount (wegive__Amount__c)
At least one of the donor fields must match an existing donor in WeGive

Pledge Matching & Create/Update Logic

When WeGive Exports a Pledge to Salesforce

The integration uses the following logic to determine whether to create a new Pledge or update an existing one:

Step 1: Check for Existing Salesforce Pledge ID

If the WeGive pledge has a salesforce_id: The integration UPDATES the existing Pledge record in Salesforce
If no salesforce_id exists: The integration CREATES a new Pledge record in Salesforce

Note: Unlike donors and transactions, pledges are NOT matched by any criteria other than the stored Salesforce ID. Each WeGive pledge maps to exactly one Salesforce pledge record.

When Salesforce Exports a Pledge to WeGive

Step 1: Check for Existing WeGive Pledge

The integration searches for an existing pledge by salesforce_id
If found, it updates that pledge
If not found, it creates a new pledge

Step 2: Verify Required Associations During import, the integration must find:

A donor in WeGive matching either the wegive__Contact__c or wegive__Account__c field
If a campaign ID is present, a campaign matching wegive__Campaign__c
If a fund ID is present, a fund matching the fund reference field

If the donor cannot be found, the import throws an exception and the pledge is not created.

Why This Matters

This matching logic ensures:

Each WeGive pledge maps to exactly one Salesforce Pledge record
Donor, campaign, and fund relationships are maintained correctly
Pledge payment schedules remain consistent across both systems
No duplicate pledges are created during sync operations

Payment Tracking

The Pledge object tracks payment progress through several calculated fields:

In Salesforce (if configured):

Number of paid installments
Total paid amount
Remaining balance
Last donation date
Next donation date
Status (Active/Closed)

In WeGive:

Pledges track all transactions associated with them
The next_installment_date is updated as payments are received
Status is automatically updated based on payment progress and dates

When a transaction is marked as a pledge payment in WeGive, it’s linked to the pledge via the pledge_id field on the transaction.