Configuring Salesforce State and Country Picklist Mappings in WeGive

When your Salesforce org has State and Country Picklists enabled, address fields on the Contact record work differently than orgs using free-text fields. Instead of a single MailingState text field, Salesforce maintains paired fields — a code field (e.g., MailingStateCode) that stores the ISO abbreviation, and a display field (e.g., MailingState) that shows the full name. The code field is the canonical, writable field.

This guide explains how to configure your WeGive ↔ Salesforce field mappings so that state and country data syncs correctly in both directions.

Before You Start

Confirm that State and Country Picklists are enabled in your Salesforce org. You can check this under Setup → State and Country/Territory Picklists. If picklists are not enabled, your org uses free-text address fields and this guide does not apply — the default WeGive mappings will work without changes.

Why Special Mappings Are Needed

WeGive stores a single value for state and country on each address (e.g., "CO" or "Colorado"). When Salesforce picklists are enabled, pushing a full state name like "Colorado" to the MailingStateCode field will fail because Salesforce expects an ISO code like "CO". Similarly, pulling from the wrong Salesforce field can write full names back into WeGive when you want codes.

To handle this correctly, each state and country field requires two one-directional mapping rules instead of a single bidirectional rule:

• Export (push to Salesforce): Maps a WeGive code accessor to the Salesforce code field, ensuring ISO codes are sent.

• Import (pull from Salesforce): Maps the Salesforce code field to the WeGive database column, ensuring ISO codes are stored.

Required Mapping Rules

Navigate to Data → Integrations → Salesforce → Mapping Rules and open the Individuals section. You need to add 8 mapping rules total — 4 for the primary (Mailing) address and 4 for the secondary (Other) address.

Mailing Address

Other Address

Note: WeGive's secondary address is called billing_address internally, which corresponds to the Other Address fields on the Salesforce Contact record.

How to Add Each Rule

For each row in the tables above:

1. Click Add New Rule in the Individuals section.

2. Enter the Salesforce Field name in the "Integration Field" input (e.g., MailingStateCode).

3. Enter the WeGive Field value in the "WeGive Field" input (e.g., mailing_address.state_code).

4. Set the Direction dropdown to either export or import as indicated.

5. Click Save on the dialog.

After adding all 8 rules, click the Save button on the Individuals section to persist your changes.

Important: Remove Conflicting Rules

If your Individuals section already has bidirectional (↔) mappings for any of these fields — such as MailingState, MailingCountry, OtherState, or OtherCountry — you should remove them before adding the rules above. Bidirectional mappings to the full-name fields will conflict with the code field mappings and cause sync errors.

Fields to look for and remove if present:

• MailingState (bidirectional)

• MailingCountry (bidirectional)

• OtherState (bidirectional)

• OtherCountry (bidirectional)

Data Validation

This mapping pattern has a built-in validation benefit. If a state or country value in WeGive is not a valid ISO code (for example, if someone entered "British Columbia" instead of "BC"), the export to Salesforce will fail with a picklist validation error. This surfaces data quality issues rather than silently syncing bad values — the sync error will appear in your integration logs, letting you know which records need correction in WeGive.

Troubleshooting

INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST error on sync A state or country value in WeGive is not a valid ISO code for that Salesforce picklist. Check the donor's address in WeGive and correct the value to a valid ISO code (e.g., "CA" instead of "California", "US" instead of "United States").

FIELD_INTEGRITY_EXCEPTION error on sync You may have a mapping pushing to both the code field and the full-name field simultaneously. Verify that you only have the code field mappings listed above and remove any mappings targeting MailingState, MailingCountry, OtherState, or OtherCountry.

State pulls back as full name (e.g., "Hawaii" instead of "HI") The import mapping may be pulling from the display field (MailingState) instead of the code field (MailingStateCode). Verify the Integration Field value in your import rule uses the Code variant.