> ## 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.
# Configuration Options
> Detailed configuration options for the WeGive Salesforce integration
This page explains what the Salesforce integration settings do to your data. Where each control lives on the screen, and what it is called there, is in the [Dashboard Settings Reference](/external/onboarding/salesforce-npsp/dashboard-settings). The order in which to configure them during an implementation is in the [Sandbox-First Implementation Guide](/external/onboarding/salesforce-npsp/install-setup/implementation-guide#phase-5-configure-the-integration-in-the-test-dashboard).
All settings live in the WeGive dashboard under **Settings > Integrations > Salesforce NPSP**, mostly on the **Sync Configuration** tab. Setting keys shown in code font are the names that appear in integration logs and in conversations with WeGive support.
## Environment matching
WeGive detects whether the authorized org is a Sandbox or Production. The connection succeeds only when the WeGive dashboard and the Salesforce org are the same type: Test with Sandbox, Live with Production. Authorization uses OAuth 2.0 through an External Client App; no Salesforce username or password is stored in WeGive. See [External Client App and Connection Setup](/external/onboarding/salesforce-npsp/install-setup/connect-app-setup).
## Sync direction
Three layers of switches decide what moves and which way.
**Enable Integration** (`enabled`), on the Connection tab, is the master switch. When off, nothing is pushed or pulled and the header badge reads Disabled.
**Two-way sync**, **CRM sync**, and the five **Track** switches under Core Settings are presented on screen as master and per-domain switches. They are stored as settings but are not consulted by the sync code reviewed for these docs, so do not rely on them to stop or start a direction; see [Known differences](/external/onboarding/salesforce-npsp/dashboard-settings#known-differences-between-the-screen-and-behavior). To make WeGive a read-only consumer of Salesforce data, turn off every Push toggle under Entity Pull & Push and WeGive4Salesforce Pushes; to make Salesforce a read-only destination, turn off every Pull toggle.
**Entity Pull & Push** gives one Pull and one Push toggle per object. A common pattern is to pull everything the org already manages in Salesforce and push only what WeGive originates. For example, an org that maintains campaigns and GAUs in Salesforce and never creates them in WeGive would turn on Pull campaigns and Pull funds but leave Push campaigns and Push funds off, so WeGive cannot create stray records.
Turning on a previously-off Pull toggle (soft credits, pledges, fund allocations, contact-role soft credits, etc.) on an org that has been syncing for a while does **not** trigger a full historical pull of that object. The next scheduled pull uses the same "since last successful sync" window as every other already-enabled object — often as recent as the last 15 minutes — so any pre-existing Salesforce records for that object that haven't changed since are never pulled in. This is silent: no error, no log entry calling out the gap. If you need the pre-existing history for a newly-enabled object, ask WeGive support for a one-time backfill of that model; don't assume it will appear on its own.
Some objects are one-directional by nature. Companies (Organization Accounts) are pulled only; WeGive writes them as part of donor pushes. Merge detection for Contacts and Accounts is pull only. Everything under **WeGive4Salesforce Pushes** (payouts, communication lists, fundraisers, and the four event objects) is push only, because those objects exist only in the WeGive4SF package and Salesforce is never their source.
### What is never pushed
Some records are held back regardless of the toggles above. Test-mode transactions and test recurring plans are never pushed. Failed transactions are pushed only if they already have a Salesforce record to update. Marketing contacts (people from external systems, not donors) are never pushed as Contacts. Records listed under **Settings > Integrations > Integration Locks** are skipped until unlocked. Stored cards and bank accounts are pushed on their own only to update a payment method that already exists in Salesforce; new ones are created as part of the gift or recurring plan push.
Campaign donors and communication list donors can be switched to a batch mode per integration, which turns off their real-time pushes in favor of scheduled bulk uploads. Tag assignments are always sent through the bulk pipeline, never in real time.
Pulls of deleted and merged records run only on the primary pull column (`pull_by`), not on any secondary pull columns configured for the integration.
## Deleted record sync
Each toggle under **Deleted Record Sync** makes a Salesforce deletion delete the matching WeGive record on the next pull. These are off by default and should stay off unless the organization treats Salesforce as the system of record for deletions. A Contact deleted in Salesforce with the donor toggle on removes the donor and their giving history from WeGive. The reverse never happens: deleting a donor in WeGive does not delete the Contact.
Tag assignments and the event objects handle deletion differently; WeGive stamps a deleted timestamp on the Salesforce record rather than deleting it. See [Tags](/external/onboarding/salesforce-npsp/data-mapping/tag) and [Events, Tickets & Registrations](/external/onboarding/salesforce-npsp/data-mapping/event).
## Contact filter
**Sync contacts with emails only** (`contacts_with_emails_only`) imports only Contacts that have at least one email address. It is on by default because WeGive's marketing and portal features key on email, and because most NPSP orgs hold many Contacts (spouses, deceased donors, legacy imports) that have no digital relationship to maintain. Turning it off imports every Contact on the next pull, which can be tens of thousands of records and a corresponding number of API calls.
## Sync timing
Pushes from WeGive to Salesforce are delayed slightly to keep related records in the right order: about five minutes for most objects, about two and a half minutes for recurring donation and communication-list-donor changes. Pulls run on the schedule set by **Pull frequency (minutes)**, which defaults to 15. The **Sync** button on the Connection and Actions tabs runs a pull immediately. Shortening the pull frequency raises API consumption in proportion; check the org's daily API allocation before going below the default.
A separate, WeGive-support-only **Realtime push** flag exists for orgs that need near-zero push delay (for example, high-volume recurring-gift flows where ordering races become common). It is off by default for every org and is not self-service on the dashboard; ask WeGive support if your integration needs it.
## Stage names
WeGive's transaction statuses (success, pending, refunded, failed) do not exist in Salesforce; Opportunities have a Stage instead. Two settings groups translate between them.
**Stage Names, Push** (`stage_success`, `stage_pending`, `stage_refunded`, `stage_failed`) are the Stage values WeGive writes when it pushes a gift. Each must match a value in the org's Opportunity Stage picklist exactly, including case. A mismatch fails every transaction push. Success covers both WeGive's Success and Processing statuses.
**Stage Names, Pull** are additional Stage values to recognize when importing gifts, because historical Opportunities often use Stages the org no longer writes ("Posted", "Closed - Reversed", "Cancelled"). WeGive checks these lists first, then the push stage names, then built-in Salesforce defaults such as Closed Won and Closed Lost. A Stage that matches nothing imports as **failed**. If imported gifts unexpectedly show as failed in WeGive, the Stage is missing from these lists.
## Record types
**Tax deductible record type ID** and **Service revenue record type ID** are the Opportunity record types WeGive assigns when it pushes a gift, depending on whether the gift is tax-deductible. Both are Salesforce record type IDs, not names.
**Household record type name** and **Non-household record type name** tell WeGive which Account record type to treat as a household and which as an organization. Defaults are `Household Account` and `Organization`. Change them only if the org renamed NPSP's record types. **Primary contact column** is the Account field that identifies the primary household member; NPSP's default is `npe01__One2OneContact__c`.
**Service Revenue Record Types** and **Hidden Record Types** (`service_revenue_record_types`, `hidden_record_types`) filter what is imported. Opportunities with a service revenue record type import as non-tax-deductible transactions and are excluded from tax receipts and statements. Opportunities with a hidden record type are not imported at all and never appear to donors. Use hidden record types for anything that is not a gift: grants, in-kind gifts, proposals, pledges tracked as Opportunities, matching gifts awaiting payment. Enter record type API names, not labels.
## Payment methods
**Payment Method Labels** (`card_payment_method_name`, `bank_payment_method_name`, `paypal_payment_method_name`) are the values WeGive writes to the Payment Method field on Payments and Opportunities. Set them to match the picklist values the org already uses so reports and roll-ups keep working.
**Push payment methods to Salesforce** and the **Payment Method Push** section are a separate, optional feature: pushing stored cards and bank accounts as records on a custom object, with field mappings under the Payment Methods object on the Mapping Rules tab. It is off by default and only relevant to orgs that need payment instrument records in Salesforce.
## Soft credits
WeGive imports Account Soft Credits and Partial Soft Credits by default and consolidates them into one soft credit object. **Pull contact role soft credits** additionally imports soft credits from `OpportunityContactRole` records, for orgs that use contact roles rather than NPSP's soft credit objects. Off by default.
## Processing options
**Send processing ACH as success** (`send_processing_ach_as_success`) treats ACH gifts that are still processing as successful when pushing, so the Opportunity closes immediately rather than after bank settlement. **On by default** for every integration. Orgs that reconcile to bank deposits and want the Opportunity to wait for settlement should turn it off; leave it on if giving totals should reflect commitments immediately.
**Push both Contact and Account on recurring donations** (`push_rd_household_for_individuals`) populates both lookups on a Recurring Donation: the household Account on an individual's plan, and the primary Contact on a company's plan. New Salesforce integrations ship with this **on by default** as of a 2026-05-27 change; integrations connected before that date were left off (`false`) and were not automatically switched over. Check this setting on an older integration rather than assuming it matches the current default — an org that relies on NPSP household roll-ups for recurring giving needs it on.
## Mapping rules
The **Mapping Rules** tab controls field-level mappings for every object. Each object shows its default rules and lets you add more. A rule pairs a Salesforce field API name with a WeGive field API name and a direction: Bi-directional, Import only, or Export only. The valid WeGive field names for each object are listed on that object's page under [Data Mapping](/external/onboarding/salesforce-npsp/data-mapping/overview).
Every new integration is seeded with a default rule set covering Contacts, Accounts, Households, Campaigns, Opportunities, Payments, Recurring Donations, Pledges, Funds, and the WeGive4SF objects. These appear on the Mapping Rules tab as the starting rules for each object and can be edited or deleted like any other rule. Deleting a default rule removes that field from the sync unless the integration also sets it hard-coded. The per-object pages mark which rows come from default rules.
Rules combine with the built-in defaults in a fixed order. On export, WeGive builds the default payload for the record first, then applies each rule on top: a rule for a Salesforce field replaces the default value for that field, a rule whose WeGive field is empty on that record is skipped so the default survives, and a **Literal Value** rule writes the literal itself (the text `true` becomes a real checkbox value). On import, a rule that targets a WeGive field replaces any default that would have filled the same field, and nested WeGive paths such as `mailing_address.city` are supported. **Create Only** rules are applied only when the Salesforce record is first created and are left out of later updates, so a value set in Salesforce afterward is preserved.
Two things fail rules silently. First, field-level security: the integration user must have read and edit access to every mapped Salesforce field, or the whole record fails on push. Second, picklists: Salesforce rejects a value that is not in a restricted picklist without raising an error WeGive can see, so the value simply disappears. Align WeGive's values with the org's picklist before mapping.
Custom objects beyond those in the WeGive4SF package can be mapped on request; there is no self-serve interface for adding a new object.
## Settings managed by WeGive
A few settings are not on the dashboard and are set by WeGive support when an org needs them: `uses_payments` (sync against NPSP Payments rather than Opportunities alone; on for most NPSP orgs), `fund_api_name` and `pledge_api_name` (alternate object names for orgs with custom GAU or pledge objects), `sync_all_recurring_donations` (pull inactive Recurring Donations as well as active), `is_legacy` (an older field mapping set for orgs connected before several NPSP fields existed), and the master flag that allows payment method sync to be offered at all. If a behavior on the per-object pages depends on one of these, the page says so.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.