npsp-household-accounts

# NPSP Household Accounts

Use this skill when configuring the Nonprofit Success Pack (NPSP) Household Account model — including household naming formats, greeting strings, primary contact designation, and the correct procedure for merging or splitting duplicate households. This skill does NOT apply to Financial Services Cloud (FSC) Household Groups, which use a fundamentally different AccountContactRelationship junction model.

---

## Before Starting

Gather this context before working on anything in this domain:

- Confirm NPSP is installed and the org uses the **Household Account** model, not the legacy Individual/Bucket Account model. Navigate to NPSP Settings > Households to verify.
- Identify which Contacts already have manually customized household names (the `npo02__SYSTEM_CUSTOM_NAMING__c` flag on the Account will be set to a non-null value). These accounts will NOT auto-update on Contact changes until the flag is cleared.
- Know the Salesforce edition and NPSP package version — Household Naming format tokens (e.g., `{!{!FirstName}} {!LastName}`) are template strings evaluated by NPSP triggers; they are not standard Salesforce formula syntax.
- Confirm whether any deduplication work is in scope. If so, plan to use NPSP's Merge Duplicate Contacts flow — NEVER the native Salesforce Account or Contact merge UI.

---

## Core Concepts

### 1. Auto-Enrollment and the Household Account Record Type

When a new Contact is created in an NPSP org using the Household Account model, NPSP automatically creates (or assigns) a Household Account with the record type `HH_Account`. The default naming pattern is `[Last Name] Household`. The Account holds three generated fields:

- **Name** (`Name`) — the public household name (e.g., "Smith Household" or "Smith and Jones Household")
- **Formal Greeting** (`npo02__Formal_Greeting__c`) — used on printed correspondence (e.g., "Mr. John Smith and Ms. Jane Jones")
- **Informal Greeting** (`npo02__Informal_Greeting__c`) — used in casual outreach (e.g., "John and Jane")

These three fields are regenerated by NPSP Apex triggers whenever a Contact's name fields change, according to the format strings configured in NPSP Settings > Households > Household Naming.

### 2. The "Customized" Flag and Manual Overrides

If a user edits the Household Account Name, Formal Greeting, or Informal Greeting fields directly, NPSP sets an internal customization flag (`npo02__SYSTEM_CUSTOM_NAMING__c`) on the Account. Once this flag is set, NPSP stops auto-updating that field — the manual value is preserved indefinitely. This is intentional behavior for households whose naming cannot follow a formula (e.g., donors who prefer a non-standard name). To resume auto-generation, the admin must clear the customized flag via the "Refresh Household Names" button in NPSP Settings or via an Apex call to `HH_HouseholdNaming.refreshAllHouseholdNaming()`.

### 3. Household Naming Format Tokens

NPSP naming strings use a double-brace token syntax:

- `{!{!FirstName}} {!LastName}` — evaluates per Contact and concatenates with NPSP's configured connector (e.g., " and ")
- Standard tokens: `{!Salutation}`, `{!FirstName}`, `{!LastName}`, `{!npo01__WorkEmail__c}`

Tokens are resolved by NPSP Apex — they are NOT Salesforce formula language. Putting them in formula fields or Flow formulas will not work.

### 4. Merging Households — NPSP Flow vs Native Merge

NPSP Household Accounts carry rollup fields (total giving, last gift date, etc.) that are maintained by NPSP Apex triggers. When two household Contacts are duplicates:

- **Correct path:** Use the **NPSP Find Duplicate Contacts** or **Merge Duplicate Contacts** flow available from a Contact record. This flow merges Contact records using NPSP-aware logic that re-fires household naming triggers, re-calculates rollups, and preserves relationship records.
- **Wrong path:** Using the native Salesforce Account merge UI (`/merge?mergeType=Account`) or the standard Contact merge bypasses all NPSP triggers. The surviving Account will have stale `npo02__TotalOppAmount__c`, incorrect household names, and orphaned `npe4__Relationship__c` records pointing at the deleted Contact.

---

## Common Patterns

### Pattern 1: Household Naming for Mixed-Last-Name Couples

**When to use:** Two Contacts in the same household have different last names (e.g., one donor kept their maiden name after marriage, or unmarried partners share a household).

**How it works:**
1. Navigate to NPSP Settings > Households > Household Naming.
2. Set the **Household Name Format** to `{!LastName}` with connector set to " and " — NPSP will produce "Smith and Jones Household."
3. Optionally use `{!{!FirstName}} {!LastName}` as the Formal Greeting format to produce "Jane Smith and John Jones."
4. If you need an entirely custom name (e.g., "The Smith-Jones Family"), edit the Account Name directly. NPSP will set the customization flag and stop auto-updating that field. All other fields can still auto-update if not also manually edited.

**Why not the alternative:** Do not attempt to create a formula field on Account that concatenates Contact names — Contacts are children of the Account and cannot be referenced in Account formula fields.

### Pattern 2: Assigning a Primary Contact to a Household

**When to use:** A household has multiple Contacts and you need to designate one as the primary for mail merge, correspondence, or reporting.

**How it works:**
1. On the Contact record, set the `npo02__Household_Naming_Order__c` field to `0` (lowest value = primary). Other household members get higher values (1, 2, etc.).
2. NPSP uses this order to determine which Contact's name appears first in generated household names and greeting strings.
3. The `Primary_Contact__c` field on the Household Account is a lookup that NPSP also populates — however, directly writing to `Primary_Contact__c` does not update the naming order; you must use the `Household_Naming_Order__c` on Contact.

**Why not the alternative:** Do not rely on Contact creation order to determine naming order — NPSP sorts by the `Household_Naming_Order__c` value, not by record ID or CreatedDate.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Two Contacts with different last names in one household | Configure household name format to use Last Name token with " and " connector | NPSP concatenates tokens across all household members using the configured connector |
| Household name must be fully custom (e.g., family trust name) | Edit Account Name directly; accept customization flag | NPSP preserves manually entered names and flags them so auto-update stops |
| Merging two duplicate household Contacts | Use NPSP Merge Duplicate Contacts flow from Contact record | Native merge bypasses NPSP triggers and corrupts rollup totals |
| Household name stopped updating after Contact name change | Check for customization flag on Account; clear it via Refresh Household Names | Manually overridden names hold a flag that blocks NPSP auto-update |
| Contact should belong to an Organization Account, not a Household | Move Contact to existing Organization Account via the Account lookup; NPSP will leave the household or create a new one depending on settings | NPSP supports both Household and Organization account types; Organization accounts are not auto-named |

---

## Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. **Verify model and settings:** Confirm NPSP is installed with Household Account model active. Go to NPSP Settings > Households and note the current Name Format, Formal Greeting, and Informal Greeting strings before making any changes.
2. **Audit customized households:** Run a SOQL query for `SELECT Id, Name, npo02__SYSTEM_CUSTOM_NAMING__c FROM Account WHERE RecordType.Name = 'Household Account' AND npo02__SYSTEM_CUSTOM_NAMING__c != null` to identify households with manual overrides before configuring naming changes — bulk name refreshes will overwrite them if the flag is cleared.
3. **Configure naming format:** Update the Household Name Format, Formal Greeting Format, and Informal Greeting Format strings in NPSP Settings > Households > Household Naming. Use NPSP's documented token syntax (double-brace `{!Field}`).
4. **Refresh household names:** After changing format strings, click "Refresh Household Names" in NPSP Settings to trigger a batch re-generation of all household names. Monitor the batch job status in Setup > Apex Jobs.
5. **Designate primary contacts:** For households where naming order matters, set `npo02__Household_Naming_Order__c` on each Contact — 0 for primary, 1+ for others. Verify the Household Account Name and greetings regenerate correctly.
6. **Merge duplicates safely:** For any duplicate household Contacts, navigate to the duplicate Contact record, click Find Duplicates, and use the NPSP Merge Duplicate Contacts flow. Confirm rollup fields on the surviving Household Account reflect the combined giving history.
7. **Validate:** Spot-check Household Account Name, Formal Greeting, Informal Greeting, and rollup totals on a sample of merged or renamed households before closing the task.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] NPSP Household Account model confirmed active (not Individual/Bucket model)
- [ ] Household Name Format, Formal Greeting, and Informal Greeting strings verified in NPSP Settings
- [ ] Batch name refresh completed and Apex Jobs show no failures
- [ ] Any manually customized household names audited and intentional overrides documented
- [ ] Duplicate household merges performed using NPSP flow (not native Account merge UI)
- [ ] Rollup totals (`npo02__TotalOppAmount__c`, `npo02__NumberOfClosedOpps__c`) verified on surviving household after any merge
- [ ] Primary Contact naming order (`npo02__Household_Naming_Order__c`) set correctly for multi-member households

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Native Account merge corrupts NPSP rollups** — Using the standard Salesforce Account merge UI bypasses all NPSP Apex triggers. The surviving account will have stale rollup fields, orphaned Relationship records, and possibly an incorrect household name. This damage is difficult to reverse without re-running full NPSP rollup recalculations and manually fixing Relationship records.
2. **Customization flag silently blocks name updates** — A household whose name was ever manually edited will have `npo02__SYSTEM_CUSTOM_NAMING__c` set. NPSP will not regenerate the name even when Contact names change. This creates a silent divergence between Contact names and Account display names that is easy to miss in production.
3. **NPSP token syntax is not Salesforce formula syntax** — Naming format strings use NPSP's own `{!Field}` template parser, not Salesforce formula language. Standard formula functions (e.g., `UPPER()`, `IF()`) do not work in these format strings and will render as literal text.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| Configured Household Naming Settings | NPSP Settings > Households with confirmed Name Format, Formal Greeting, and Informal Greeting strings |
| Refreshed Household Names | Batch job result showing all household accounts regenerated with new format |
| SOQL audit query | Query identifying households with manual customization flags for documentation |
| Merge completion record | Notes confirming which Contact was retained, which was deleted, and that rollup totals were verified post-merge |

---

## Related Skills

- `financial-account-setup` — For FSC Financial Accounts under household models (FSC uses ACR junction — incompatible with NPSP direct lookup)
- `duplicate-management` — For platform-level duplicate rules and matching rules that feed into the NPSP merge flow
- `gift-entry-and-processing` — NPSP gift entry relies on correct Household Account association for rollup accuracy