> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pledge

> Mapping between WeGive Pledges and Salesforce custom Pledge objects

**Salesforce Object:** `wegive__Pledge__c` (WeGive managed package object)<br />**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.

<Note>
  One legacy custom implementation uses a different object and field set, driven by mapping rules. Everything below describes the standard `wegive__Pledge__c` object shipped in the WeGive managed package.
</Note>

***

## 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 (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

Pledge pulls and pushes are controlled by the **Pull pledges** and **Push pledges** toggles in Sync Configuration. Related settings:

| Setting | Effect |
| :- | :- |
| `pull_deleted_pledges` | Remove WeGive pledges whose Salesforce pledge was deleted |
| `pledge_api_name` | Object queried for deleted pledges (defaults to `wegive__Pledge__c`). Regular pulls and pushes always use `wegive__Pledge__c` |
| `household_record_type_name` | Account Record Type name that identifies Household Accounts when resolving the donor on import |

***

## Sync Triggers

### From WeGive to Salesforce (Export)

Pledge data is exported when a pledge is created or updated in WeGive (e.g., amount changed, dates updated, description or hidden status changed). Pledge payments (transactions) do not trigger a pledge push.

### From Salesforce to WeGive (Import)

* **Last Modified Date:** WeGive polls `wegive__Pledge__c` for records modified since the last sync
* **Modified Field Tracking:** Only pledges with a `LastModifiedDate` newer than the last successful sync are pulled

### Deleted Pledges

When `pull_deleted_pledges` is enabled, pledges with `IsDeleted = true` in the sync window soft-delete the matching WeGive pledge.

***

## Sync Process Overview

### Pulling Data from Salesforce

The pull reads a fixed field set: `Id`, `CreatedDate`, `Name`, `wegive__Account__c`, `wegive__Account__r.RecordType.Name`, `wegive__Contact__c`, `wegive__Amount__c`, `wegive__Campaign__c`, `wegive__Description__c`, `wegive__Start_Date__c`, `wegive__End_Date__c`, `wegive__Next_Installment_Date__c`, `wegive__Installment_Period__c`, `wegive__Is_Hidden__c`. Import mapping rules do not change the pledge fields; any values not mapped to pledge attributes are stored as custom field values.

The import:

* Matches the WeGive pledge by stored `salesforce_id`, creating a new pledge if none exists
* **For new pledges only**, resolves the donor from `wegive__Contact__c` and `wegive__Account__c`. 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 with "No donor found" if neither resolves
* Links the campaign matching `wegive__Campaign__c`
* Converts the installment period (see Installment Frequency Mapping)
* Writes description, hidden status, dates, amount and next installment date

<Warning>
  **Auto-bill lock.** If the WeGive pledge has automatic billing enabled, WeGive owns the billing schedule and the import does not overwrite `total_amount`, `start_date`, `end_date`, `installment_frequency`, `number_of_installments` or `next_installment_date`. Description and hidden status are still updated. Pledges without auto-bill take all values from Salesforce.
</Warning>

Funds are **not** imported for pledges.

### Pushing Data to Salesforce

Before pushing, the integration pushes the donor, campaign and fund if any of them lacks a Salesforce ID. The payload is then built from the hard-coded fields below plus any Pledge export mapping rules. The pledge's attributes, custom fields, donor, campaign and fund attributes are available to rules.

### 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 |
| wegive\_\_Contact\_\_c | Donor Salesforce ID | `donor.salesforce_id` | Both Ways | Hard-coded | Export: donor's Contact ID. Import: used to resolve the donor on create |
| wegive\_\_Account\_\_c | Donor Salesforce Account ID | `donor.salesforce_account_id` | Both Ways | Hard-coded | Export: donor's Account ID. Import: used with the Account Record Type to resolve the donor on create |
| wegive\_\_Campaign\_\_c | Campaign Salesforce ID | `campaign.salesforce_id` | Both Ways | Hard-coded | |
| wegive\_\_Amount\_\_c | Total Amount | `total_amount` | Both Ways | Hard-coded | Dollars in Salesforce, cents in WeGive. Import respects the auto-bill lock |
| wegive\_\_Start\_Date\_\_c | Start Date | `start_date` | Both Ways | Hard-coded | Export `Y-m-d` in the organization timezone. Import respects the auto-bill lock |
| wegive\_\_End\_Date\_\_c | End Date | `end_date` | Both Ways | Hard-coded | Same as Start Date |
| wegive\_\_Next\_Installment\_Date\_\_c | Next Installment Date | `next_installment_date` | Import from Salesforce | Hard-coded | Respects the auto-bill lock. Available to export rules as `Y-m-d` |
| wegive\_\_Installment\_Period\_\_c | Installment Frequency | `installment_frequency` | Both Ways | Hard-coded | See Installment Frequency Mapping. Import respects the auto-bill lock |
| wegive\_\_Description\_\_c | Description | `description` | Both Ways | Hard-coded | Truncated to 255 characters on export |
| wegive\_\_Is\_Hidden\_\_c | Hidden Status | `is_hidden` | Both Ways | Hard-coded | |
| wegive\_\_Last\_Sync\_Date\_\_c | Last Sync | now | Export to Salesforce | Hard-coded | ISO 8601 timestamp |
| wegive\_\_WeGive\_Entity\_\_c | WeGive Entity | Organization setting | Export to Salesforce | Hard-coded | Multi-entity orgs only |
| CreatedDate | Created At | `created_at` | Import from Salesforce | Hard-coded | Read from Salesforce |
| Any custom field | Custom field or attribute | Mapping rule path | Export to Salesforce | Configurable (mapping rule) | Import values that are not pledge attributes are stored as custom fields |

## Important Notes

### Donor Association

On export, both `wegive__Contact__c` and `wegive__Account__c` are sent with whatever IDs the donor has.

On import (new pledges only), the donor is resolved as follows:

1. If `wegive__Account__c` is set and the Account's Record Type is not the household Record Type (`household_record_type_name`, default "Household Account"), the company donor with that Account ID is used
2. Otherwise, if `wegive__Contact__c` is set, the donor with that Contact ID is used
3. Otherwise, if only an Account ID is present, the company donor with that Account ID is used

If no donor is found the import fails. Existing pledges keep their donor.

### Installment Frequency Mapping

| WeGive Value | Salesforce Value |
| :- | :- |
| 1 | "1 Payment" |
| 4 | "4 Payments" |
| 8 | "8 Payments" |
| monthly | "Monthly" |
| quarterly | "Quarterly" |
| annually | "Annually" |

On import the match is case-insensitive and also accepts the bare values "1", "4" and "8". An unrecognised Salesforce value leaves the frequency empty. On export, a WeGive value not in the table is sent as-is.

<Note>
  Pledges share the same `FREQUENCY_TO_SF`/`SF_TO_FREQUENCY` constant maps as Recurring Donations — confirmed at `Salesforce.php:84-103` (export) and `:93-103` (import), referenced directly from `compilePledgePayload()` (`:5948`, `:5995`) and `importPledge()` (`:3448-3451`). There is no separate Pledge-specific frequency table; it is the identical mapping used for `npsp__InstallmentFrequency__c` on Recurring Donations.
</Note>

### Campaign and Fund

* **Campaign:** exported to `wegive__Campaign__c` and imported from it. The campaign is pushed first if it has no Salesforce ID
* **Fund:** the fund is pushed first if it has no Salesforce ID, but there is no fund field on `wegive__Pledge__c`. Fund is neither exported nor imported for pledges

### Date Formatting

Start and end dates are exported as `Y-m-d` in the organization's timezone.

### Number of Installments

`number_of_installments` is not read from Salesforce. New pledges created by import get 0; existing pledges keep their current value.

### Required Fields

**For WeGive to Salesforce:** a donor with a Contact or Account Salesforce ID, total amount, start date.

**For Salesforce to WeGive:** `wegive__Amount__c`, and either `wegive__Contact__c` or `wegive__Account__c` matching an existing WeGive donor (new pledges).

***

## Pledge Matching & Create/Update Logic

### When WeGive Exports a Pledge to Salesforce

* If the pledge has a `salesforce_id`: **UPDATE** the existing record
* If not: acquire a per-pledge lock and **CREATE** a new record, then store its ID

Pledges are matched only by stored Salesforce ID.

### When Salesforce Exports a Pledge to WeGive

1. Search for an existing pledge by `salesforce_id`; update it, or create a new one
2. For a new pledge, resolve the donor (see Donor Association); fail if not found
3. Link the campaign if `wegive__Campaign__c` matches a WeGive campaign
4. Apply the imported values, honoring the auto-bill lock

***

## Payment Tracking

Standard `wegive__Pledge__c` carries no payment progress fields. Counts of paid installments, total paid, remaining balance, last and next donation date, and an Active/Closed status are pushed only by one legacy custom implementation and are not part of the managed package object.

In WeGive, pledges track their transactions through the `pledge_id` field on the transaction, and a transaction imported from an Opportunity is linked to its pledge when a mapping rule supplies `pledge.salesforce_id`.

## Related Documentation

* [Data Mapping Overview](./overview) - object index and cross-cutting data conventions
* [Opportunity & Payment](./opportunity) - pledge payments as transactions
* [Contact](./contact) and [Account](./account) - the pledging donor

*Verified against the integration source, September 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.