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

# Data Mapping Overview

> How WeGive objects map to Salesforce NPSP objects, and the conventions that govern every field mapping

This page is the index for the WeGive Salesforce NPSP field mapping reference. It lists every object pair the integration syncs, links to the field-by-field detail for each, and documents the conventions (amount units, dates, picklists, sync direction) that apply across all of them.

This is reference material. To learn how to add or change a mapping in your own account, see [Add or edit a field mapping](#) in the Knowledge Base. *(Editor note: link to the V2 Pylon article once published.)*

## How mapping works

WeGive syncs in two directions. It **pulls** records from Salesforce (querying by last modified date) to create or update the matching WeGive record, and it **pushes** changes from WeGive by compiling a payload for the Salesforce object. Each object is synced as a pair: one WeGive model to one Salesforce object.

For a customer-facing explanation of how the sync runs (sync toggles, what Sync All does, and scheduled timing), see [How the Salesforce Sync Works](https://help.wegive.com/articles/6819841810-how-the-salesforce-sync-works) in the Knowledge Base.

Every field mapping has a direction and a type.

**Direction** describes which way the data flows:

* **Import from Salesforce** - data flows from Salesforce into WeGive only.
* **Export to Salesforce** - data flows from WeGive into Salesforce only.
* **Both Ways** - data syncs in both directions.

**Type** describes whether the mapping can be changed:

* **Configurable** - mapped through integration settings; you can repoint or remove it.
* **Hard-coded** - built into the integration logic to handle a business rule (email selection, name defaults, amount conversion) and cannot be changed.

When you add a custom mapping rule, you enter a **WeGive API name** (for example `ends_at` or `mailing_address.city`) on the WeGive side and the Salesforce field on the other. The per-object pages below list the valid WeGive API names for each object.

## Object index

### Donor management

| WeGive object    | Salesforce object                  | Salesforce API name | Field detail         |
| ---------------- | ---------------------------------- | ------------------- | -------------------- |
| Individual donor | Contact                            | `Contact`           | [Contact](./contact) |
| Company donor    | Account (Organization record type) | `Account`           | [Account](./account) |
| Household        | Account (Household record type)    | `Account`           | [Account](./account) |

### Donation management

| WeGive object         | Salesforce object       | Salesforce API name            | Field detail                               |
| --------------------- | ----------------------- | ------------------------------ | ------------------------------------------ |
| Transaction           | Opportunity             | `Opportunity`                  | [Opportunity & Payment](./opportunity)     |
| Transaction (payment) | NPSP Payment            | `npe01__OppPayment__c`         | [Opportunity & Payment](./opportunity)     |
| Recurring plan        | NPSP Recurring Donation | `npe03__Recurring_Donation__c` | [Recurring Donation](./recurring-donation) |

The NPSP Payment object is only written when the `uses_payments` setting is enabled. See [Configuration Options](../configuration-options) for what that setting does.

### Funds and gift detail (NPSP)

| WeGive object            | Salesforce object       | Salesforce API name                | Field detail                 |
| ------------------------ | ----------------------- | ---------------------------------- | ---------------------------- |
| Designation (Fund)       | General Accounting Unit | `npsp__General_Accounting_Unit__c` | [GAU](./gau)                 |
| Fund allocation          | Allocation              | `npsp__Allocation__c`              | [Allocation](./allocation)   |
| Soft credit (company)    | Account Soft Credit     | `npsp__Account_Soft_Credit__c`     | [Soft Credit](./soft-credit) |
| Soft credit (individual) | Partial Soft Credit     | `npsp__Partial_Soft_Credit__c`     | [Soft Credit](./soft-credit) |

The GAU object API name can be overridden per org with the `fund_api_name` setting for orgs whose schema differs from NPSP defaults.

### WeGive managed package objects

These objects exist only after the WeGive managed package is installed. Their fields carry the `wegive__` namespace prefix.

| WeGive object            | Salesforce object        | Salesforce API name                   | Field detail                               |
| ------------------------ | ------------------------ | ------------------------------------- | ------------------------------------------ |
| Pledge                   | Pledge                   | `wegive__Pledge__c`                   | [Pledge](./pledge)                         |
| Communication list       | Communication List       | `wegive__Communication_List__c`       | [Communication List](./communication-list) |
| Communication preference | Communication Preference | `wegive__Communication_Preference__c` | [Communication List](./communication-list) |
| Campaign event           | Event                    | `wegive__Event__c`                    | [Events](./events)                         |
| Event ticket             | Event Ticket             | `wegive__Event_Ticket__c`             | [Events](./events)                         |
| Event registration       | Event Registration       | `wegive__Event_Registration__c`       | [Events](./events)                         |
| Campaign fundraiser      | Fundraiser               | `wegive__Fundraiser__c`               | [Fundraiser](./fundraiser)                 |
| Payout                   | Payout                   | `wegive__Payout__c`                   | [Payout](./payout)                         |

A small number of orgs use non-namespaced or alternately named fields for the Pledge and Payout objects (legacy custom builds). Those overrides are configured per integration; contact WeGive to confirm an org's object names.

### Campaign

| WeGive object | Salesforce object | Salesforce API name | Field detail           |
| ------------- | ----------------- | ------------------- | ---------------------- |
| Campaign      | Campaign          | `Campaign`          | [Campaign](./campaign) |

## Data handling conventions

These rules apply to every mapping. They are the most common source of "the value came across wrong" questions.

**Amounts.** WeGive stores money in cents; Salesforce stores dollars. The default mappings divide by 100 on push and multiply by 100 on pull. If you map the raw `amount` field directly to a Salesforce currency field you will get cents, which is almost always wrong. Use the computed `dollar_amount` value or rely on the default mapping.

**Dates.** WeGive stores `*_at` columns as UTC datetimes and `*_date` columns as dates. The integration formats dates as `YYYY-MM-DD` for Salesforce and adjusts close dates and campaign dates to the org timezone.

**Booleans.** Salesforce checkbox fields accept WeGive booleans directly; no conversion is needed.

**Picklists.** Salesforce picklist fields silently reject a value that is not in the allowed set, so a mapped value can disappear with no error. Align the values WeGive sends with the org's picklist. This is why donor State and Country are imported from Salesforce but not exported by default. Salesforce State and Country/Territory Picklists is an org-wide setting that applies to both Contact and Account. When it is enabled, state and country on both objects must be mapped through the code fields (for example `MailingStateCode`, `BillingStateCode`) using a one-directional export/import split rather than a single both-ways rule. See the [Contact](./contact) and [Account](./account) pages for the exact mappings.

**Frequency.** WeGive stores frequency as strings ("monthly") or integers (1, 4, 8). The integration translates these to NPSP's expected installment values ("Monthly", "1 Payment", and so on).

## Coming soon

The following are planned but not yet synced:

* Impact stories (Posts)
* Impact cards (Impact Numbers)
* Tasks
* Notes
* Files

## Not currently integrated

These NPSP objects are not synced and are used only for internal Salesforce processes: NPSP Data Import Batch, Deliverable (Grant Deadline), Error, Trigger Handler, Engagement Plan and Engagement Plan Templates, Level, Recurring Donation Change Log, Affiliation (`npe5__Affiliation__c`), and Relationship (`npe4__Relationship__c`).

> **Editor note - confirm before publishing.** The current live overview also lists Lead (Marketing Contact), Campaign Member, Address (`npsp__Address__c`), Donor Journey / Journey, Form and Form Submission, Tag, Designation List, and a separate P2P Fundraiser object. None of these appear in the integration source (`Salesforce.php`). Addresses sync as nested fields on Contact and Account (`mailing_address`, `billing_address`), not as a separate Address object. Confirm whether any of these object syncs actually exist before carrying them into the rewritten overview; otherwise drop them.

## Related documentation

* [Setup Requirements](../setup-requirements) - editions, permissions, and the NPSP objects the integration depends on
* [Configuration Options](../configuration-options) - settings that change what syncs and how
* Per-object field detail: [Account](./account), [Contact](./contact), [Campaign](./campaign), [Opportunity & Payment](./opportunity), [Recurring Donation](./recurring-donation), [GAU](./gau), [Allocation](./allocation), [Soft Credit](./soft-credit), [Pledge](./pledge), [Payout](./payout), [Communication List](./communication-list), [Events](./events), [Fundraiser](./fundraiser)
* To add or change a mapping in your account, see the Knowledge Base. *(Editor note: link the V2 Pylon "Add or edit a field mapping" article once published.)*