Configuring Salesforce State and Country Picklist Mappings in WeGive

State and country addresses can sync between WeGive and Salesforce in two different ways, depending on whether your Salesforce org uses State and Country Picklists. This guide shows you which setup applies to your org and exactly what to map for both Contacts (individual supporters) and Accounts (companies and households).

Start here: confirm which setup you have, then jump to the matching section below.

Before You Start: Which Setup Do You Have?

In Salesforce, go to Setup, search for State and Country/Territory Picklists, and check whether they are enabled.

• Picklists are NOT enabled (free-text fields). Your org stores state and country as plain text (for example, a single MailingState field holding "Colorado"). Use Setup A: Free-Text Address Fields.

• Picklists ARE enabled (validated codes). Your org stores paired fields: a code field (for example MailingStateCode) that holds the ISO abbreviation and a display field (for example MailingState) that shows the full name. The code field is the one you map. Use Setup B: State and Country Picklists.

If you are not sure, check the setting above before mapping. Mapping for the wrong setup is the most common cause of state and country sync errors.

Salesforce Field Names at a Glance

State and country live on different field sets for Contacts and Accounts. Use this reference when building either setup below.

Contact (individual supporter) address fields:

Account (company or household) address fields:

On the WeGive side, addresses are stored in two slots, mailing_address and billing_address. They pair to Salesforce differently by object:

• Contacts: mailing_address maps to the Salesforce Mailing address, billing_address to the Other address.

• Accounts: billing_address maps to the Salesforce Billing address, mailing_address to the Shipping address (Billing matches billing).

Setup A: Free-Text Address Fields

If your org does not use picklists, state and country are plain text and a single bidirectional rule per field is all you need. Add these in Integrations > Salesforce NPSP > Mapping Rules.

For individual supporters, open the Individuals section and add:

For companies, open the Companies (Account) section and add:

That is all that is required for free-text orgs. If you later turn on State and Country Picklists, come back and switch to Setup B.

Setup B: State and Country Picklists

When picklists are enabled, Salesforce expects an ISO code (for example "CO", not "Colorado") in the code field and silently rejects anything else. Because WeGive stores a single value per address, each field needs two one-directional rules instead of one bidirectional rule:

• Export (push to Salesforce): sends the WeGive code value to the Salesforce code field, so a valid ISO code is written.

• Import (pull from Salesforce): reads the Salesforce code field back into WeGive.

Why two rules per field (and not one bidirectional rule)

Each address value in WeGive has two forms: the stored value (state, country) and a code form (state_code, country_code).

• The stored value (state, country) is the writable field. It is what WeGive actually saves.

• The code form (state_code, country_code) is read-only. It derives the ISO abbreviation (for example "CO" or "US") from the stored value. You can read it, but you cannot write into it.

A single bidirectional rule only points at one of those fields, so it can never serve both directions:

• Point it at the code field and export works (it sends "CO"), but import has nowhere to land, because the code field is read-only. The value Salesforce sends back is lost.

• Point it at the stored value and import works, but export sends whatever is stored (often a full name like "Colorado"), which the restricted picklist silently rejects, so the value disappears with no error.

Splitting into two rules uses each field for what it can do: export from the code field so a valid ISO code goes out, and import into the stored value so the incoming code lands in a writable field.

Contact (individual supporters)

In Integrations > Salesforce NPSP > Mapping Rules, open the Individuals section and add these 8 rules.

Primary (Mailing) address:

Secondary (Other) address:

Account (companies and households)

Open the Companies (Account) section and add these 8 rules.

Primary (Billing) address:

Secondary (Shipping) address:

How to Add Each Rule

For every row in the tables above:

1. Click Add New Rule in the relevant section (Individuals or Companies).

2. Enter the Salesforce field name in the Integration Field input (for example MailingStateCode).

3. Enter the WeGive field value in the WeGive Field input (for example mailing_address.state_code).

4. Set the Direction dropdown to both, export, or import as listed.

5. Click Save on the dialog.

When you have added every rule for a section, click the Save button on that section to persist your changes.

Remove Conflicting Rules

If you switched a picklist org to Setup B but still have older bidirectional rules pointing at the display fields, remove them. A rule pushing to the display field at the same time as the code field will cause sync errors.

Remove these if present:

A Built-In Data-Quality Check (Picklist Orgs)

The picklist setup gives you a useful side effect. If a state or country value in WeGive is not a valid ISO code (for example, someone typed "British Columbia" instead of "BC"), the export to Salesforce fails with a picklist validation error and the issue appears in your integration logs. This surfaces bad data instead of silently syncing it, so you know exactly which records to correct in WeGive.

Troubleshooting

INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST on sync: a state or country value in WeGive is not a valid ISO code for that picklist. Open the supporter's address in WeGive and correct the value (for example "CA" instead of "California", "US" instead of "United States").

FIELD_INTEGRITY_EXCEPTION on sync: you likely have a rule pushing to both the code field and the display field at once. Confirm you only have the code-field rules from Setup B and remove any rule targeting MailingState, MailingCountry, OtherState, OtherCountry, BillingState, BillingCountry, ShippingState, or ShippingCountry.

State or country pulls in as the full name (for example "Hawaii" instead of "HI"): your import rule is reading the display field instead of the code field. Confirm the Integration Field value uses the Code variant (for example MailingStateCode, not MailingState).

Related Reference

For the full field-by-field mapping reference and address field paths across every object, see the Data Mapping Overview on the technical docs site.