<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=2191750074375425&amp;ev=PageView&amp;noscript=1">
Skip to content
More support
Contact us
  • There are no suggestions because the search field is empty.

Salesforce Integration Mappings

Salesforce integration includes Donor & Donation, Guest, and Volunteer sync options.

Donor and Donation Sync Process Details

When a user starts a donation sync from the Salesforce integration page, the process unfolds as follows:

Identify and handle donor information: Contact and Company Matching Criteria

Initial step when syncing a donation is to locate or create the <contact> record in Salesforce that corresponds to the donor record in BetterUnite.

When a user starts a donation sync from the Salesforce integration page, BetterUnite syncs each donation and resolves the donor’s Salesforce records in this order.

1) Contact resolution (exact decision flow)

For each donation, BetterUnite resolves the Salesforce Contact using the following rules:

  1. If the BetterUnite contact already has SF_ID
    • If missing, sync fails for that donation (Salesforce requires last name on Contact).
    • Lookup: Salesforce Contact where Email == donor.EmailAddress1 (exact value search).
      • 1 match: use that Contact.
      • >1 matches: sync returns “Multiple contact matches” and includes the list for user choice, plus a “Create new customer” option.
      • 0 matches: create a new Salesforce Contact.
    • BetterUnite attempts to fetch that Salesforce Contact by ID.
      • If found, that Contact is used.
      • If not found (deleted/invalid in Salesforce), BetterUnite falls back to matching logic below.
  2. If no valid SF_ID is available
    • BetterUnite requires donor Last Name.
    • BetterUnite then tries email-only matching:
    • If donor email is blank, BetterUnite does not do name-based matching here; it proceeds to create a new Contact (as long as last name exists).

2) Contact create/update behavior

  • Contact field mapping uses configured Salesforce contact mappings, or default mappings if custom mapping is not configured.

  • Typical mapped fields include First Name, Last Name, Email, phones, mailing address, etc.

  • If setting is enabled and an existing Salesforce Contact is used, BetterUnite updates mapped fields when values differ.

  • BetterUnite stores the resolved Salesforce Contact ID back to BetterUnite

3) Company (Account) handling for Contacts

Company resolution is applied when creating a new Salesforce Contact and donor has CompanyName:

  • When creating a new Salesforce Contact, if CompanyName exists, it then resolves/creates the Salesforce Account by company name and sets Contact.AccountId.

  • Query Salesforce Account by exact Name (Account.Name == CompanyName).

    • If at least one match is found, BetterUnite uses the first matched Account ID.

    • If no match is found, BetterUnite creates a new Account with Name = CompanyName

  • The Contact is created with AccountId set to that resolved/created Account.

Notes:

  • Company matching is name-based only (exact equality query).

  • During contact updates, account reassignment is not part of the update path in this flow.

4) Tags (Salesforce Topics)

  • On new contact create, BetterUnite maps BetterUnite tags to Salesforce Topics:

    • Finds Topic by name, creates it if missing, then creates TopicAssignment to the Contact.
  • On contact update, BetterUnite compares tags and adds/removes TopicAssignments to align with BetterUnite tags.
  • You may need to turn on the topics feature for contact entity in your Salesforce instance for this information to be available during sync.  Refer to the Salesforce Connection Setup instructions for more information on how to turn on this feature in Salesforce.

5) Donation linkage after contact resolution

Once Contact is resolved:

  • Donation (Opportunity) is created/updated in Salesforce.

  • Opportunity is linked to the Contact (including OpportunityContactRole primary contact handling).

  • BetterUnite stores synced Salesforce IDs/status back on donation and contact records.

 

Create donation for the contact above

After the contact record is obtained or created, a Salesforce "donation" record can be established. The Salesforce nonprofit add-on transforms the standard <opportunity> entity into a donation entity. Consequently, BetterUnite will align with the "opportunity" entity in Salesforce (which will appear as a donation in Salesforce). Salesforce categorizes donations as "closed won" opportunities, so the integration stage will automatically default to this status.

Below opportunity fields are updated during donation creation:

  • Name: [Contact Name] Donation [Donation Date]
  • Description: 
    • If donation has line items, they will be summarized into text as such: [item name] (quantity)
    • If donation has a note, the note will also be appended to the description
  • StageName: "Closed Won"
  • Amount: Based on integration settings, can be intended amount, gross, net or paid amount to organization
  • CloseDate: Donation Date
  • CampaignId: Salesforce campaign id set on the mapping page
  • AccountId: If the matched contact has an account association, it will be used here to associate the opportunity with the account

 

Once the donation "opportunity" record is established in Salesforce, the integration will update the primary contact on the opportunity to the specified contact. This linkage is accomplished by creating an <OpportunityContactRole> entity in Salesforce.

If the integration settings are configured to itemize donations, the donation integration steps will be repeated for each donation component, including each gift line item, fees, and miscellaneous donation amounts, which will be integrated as separate donations.

 

Guest or Volunteer Sync

On the integration page you will see separate tabs for Guest and Volunteer sync options. Each tab will display the relevant campaign types, namely events or volunteer sign up pages. 

Within each tab, you can sync all participants for the mapped campaigns. The behavior of both guests and volunteers sync methods are identical.

The sync process will create "Campaign Member" records in Salesforce campaign for your guests.

Here are some highlights of the integration:

  • Only participants (guests or volunteers) with a contact record will be synced (i.e. if the participant has an email address associated)
  • You can run the sync as many times as you need
  • Participants with changed contacts will be reconciled so that the new campaign member with the updated contact record will be created, as a result, any campaign member that was previously created for a different contact record will be removed.
  • Salesforce has default Campaign Member Statuses as: Sent, and Responded.
  • Campaign Member statuses will be mapped as follows:
    • RSVPed => "RESPONDED",
    • CheckedIn => "RESPONDED",
    • CheckedOut => "RESPONDED",
    • Registered => "SENT",
    • NotAttending => "SENT",
    • Invited => "SENT",

Additional Donation Sync Notes

Contact matching and contact requirements

BetterUnite matches donors to Salesforce Contacts primarily by email address.

If multiple Salesforce contacts match the same email, the sync will prompt you to choose the correct contact or create a new one.

A Last Name is required to create a new Salesforce Contact. If missing, that transaction cannot create a new contact until the donor profile is updated.

Donation stage behavior

Synced donations are created as Salesforce Opportunities (Donation records in NPSP).

Stage is typically set to Closed Won.

If your Salesforce org has a Posted stage configured for Opportunity, BetterUnite can use Posted for final synced donations.

Fair Market Value (FMV) mapping

If your Salesforce org has the NPSP FMV field (npsp__Fair_Market_Value__c), BetterUnite will populate Fair Market Value for applicable gift-related transactions.

If that field is not available in your org, FMV is skipped.

Pledge Handling Details

When a BetterUnite payment is associated with a pledge, sync behavior differs from one-time donations:

BetterUnite attempts to locate and update the existing open pledge Opportunity rather than creating unrelated standalone opportunities.

Opportunity Amount reflects the total pledged amount.

Payment activity updates pledge progress and includes payment context in Opportunity details.

If your Salesforce org supports NPSP Payment records (npe01__Payment__c):

BetterUnite also creates a linked Payment record per pledge payment installment. Otherwise, pledge payments are synced as regular donation records.

 

Have more questions or need help setting up your integration?

Reach out to our support team