soft-credits-and-matching

# Soft Credits and Matching Gifts (NPSP)

This skill activates when configuring NPSP soft credit attribution, partial soft credits, or employer matching gift workflows. It covers the full lifecycle from OCR role assignment through rollup recalculation, including the known platform bug with duplicate records produced by Find Matched Gifts.

---

## Before Starting

Gather this context before working on anything in this domain:

- **NPSP rollup mode:** Determine whether the org uses Real-Time (formerly triggers-based) or Batch rollup processing. Soft credit totals on Contact and Account update differently depending on this setting — real-time mode still does NOT guarantee instant totals for soft credits; the nightly batch (`NPSP_Account_Contact_Rollup`) is the reliable path.
- **Credit type in play:** Distinguish between (a) automatic household soft credits generated by NPSP when a household member is not the primary donor, (b) explicit relationship-based soft credits where a Contact with a relationship to the donor receives credit, and (c) matching gift partial soft credits attributed to an employer Contact/Account via a separate Matching Gift opportunity.
- **Existing Matching Gift opportunity:** Find Matched Gifts requires a pre-existing Matching Gift opportunity record on the employer. If none exists, the gift cannot be matched and the button has no effect. Confirm this record exists before proceeding.
- **Known platform limit:** Running Find Matched Gifts for a donor Contact who has more than one gift linked to the same Matching Gift opportunity will produce duplicate `OpportunityContactRole` and `npsp__Partial_Soft_Credit__c` records, inflating rollup totals. Document this if encountered.

---

## Core Concepts

### Soft Credits Are Driven by OpportunityContactRole (OCR) Records

Every NPSP soft credit is an `OpportunityContactRole` record with a role value that NPSP recognizes as a soft credit role (e.g., "Soft Credit," "Household Member," "Matched Donor"). NPSP reads the `Role` field on the OCR and, if that role is in the org's configured list of soft credit roles under NPSP Settings > Contact Roles, it creates or updates a rollup contribution toward the contact's soft credit totals.

The primary donor's OCR uses role "Donor" and contributes to hard credit totals. All other roles configured as soft credit roles contribute only to soft credit rollup fields (`npsp__Soft_Credit_This_Year__c`, `npsp__Soft_Credit_Total__c`, etc.) on the Contact and Account records.

### Partial Soft Credits Use npsp__Partial_Soft_Credit__c

When the full opportunity amount should NOT be credited to a soft credit recipient (most common in matching gifts, where the employer matches only a portion), NPSP uses the `npsp__Partial_Soft_Credit__c` object. This object has:

- `npsp__Opportunity__c` — lookup to the Matching Gift opportunity
- `npsp__Contact__c` — lookup to the contact receiving partial credit
- `npsp__Amount__c` — the portion to credit
- `npsp__Contact_Role_ID__c` — lookup to the OCR record this partial credit corresponds to

If a `Partial_Soft_Credit__c` record exists for an OCR, NPSP uses the `npsp__Amount__c` field for rollup calculations instead of the full opportunity amount. Without a partial soft credit record, the full opportunity amount rolls up to every OCR soft credit recipient, which overstates giving totals.

### Rollup Fields Update via Batch — Not in Real Time

Soft credit rollup fields on Contact and Account (`npsp__Soft_Credit_This_Year__c`, `npsp__Soft_Credit_Last_Year__c`, `npsp__Soft_Credit_Two_Years_Ago__c`, `npsp__Soft_Credit_Total__c`) do NOT update synchronously when an OCR or Partial Soft Credit record is created or modified. They update only when:

1. The nightly NPSP batch job (`Schedulable_Batch_Apex` or `NPSP_Account_Contact_Rollup`) runs, or
2. A manual Recalculate Rollups operation is triggered from NPSP Settings > Batch Processing, or
3. A direct Recalculate button is used from the Contact record (available in some NPSP versions).

This is a common source of confusion: an admin creates OCR records correctly but the Contact's soft credit total shows $0 until the batch runs. This is expected behavior, not a bug.

### Matching Gifts Require a Separate Matching Gift Opportunity

Employer matching gifts in NPSP are NOT just a flag or field on the original donor opportunity. The workflow requires:

1. A separate `Opportunity` record of type "Matching Gift" on the employer's Account
2. The Find Matched Gifts action on the donor's original gift opportunity, which links the two records via the `npsp__Matching_Gift__c` lookup field and creates an OCR (role: "Matched Donor") on the Matching Gift opportunity for the employer contact

This separation means the employer receives credit via the Matching Gift opportunity record, not via a soft credit on the original donation. The employer's Account hard credit total increases; the original donor's hard credit is unaffected.

---

## Common Patterns

### Pattern: Configuring a Relationship-Based Soft Credit

**When to use:** A contact other than the primary donor solicited or influenced the gift and should receive soft credit for fundraising attribution purposes (e.g., a board member who cultivated a major donor).

**How it works:**
1. Open the Opportunity record for the gift.
2. Go to the Contact Roles related list and add the influencer contact.
3. Set the Role to a value configured as a soft credit role in NPSP Settings > Contact Roles (commonly "Soft Credit" or a custom influencer role).
4. Save. If the full amount should credit to this contact, no further action is needed.
5. If only a partial amount should credit (rare for soft credits but possible), create an `npsp__Partial_Soft_Credit__c` record with the correct amount and link it to the OCR.
6. Trigger rollup recalculation manually or wait for the nightly batch.

**Why not the alternative:** Do not duplicate the Opportunity or create a shadow gift to represent the soft credit — this inflates total gift count and hard credit totals for the org.

### Pattern: Configuring a Matching Gift Partial Soft Credit via Find Matched Gifts

**When to use:** An employer has pledged to match employee donations. The employee's gift has been recorded. The employer's Matching Gift opportunity exists.

**How it works:**
1. Verify the employer Account has an open Matching Gift Opportunity. If not, create one (Opportunity record, Close Date in the matching window, Stage = "Pledged" or as appropriate, record type = Matching Gift if available).
2. Navigate to the original employee donation Opportunity.
3. Use the Find Matched Gifts button/action. NPSP will search for Matching Gift opportunities on the donor's employer Account.
4. Select the correct Matching Gift opportunity. NPSP will:
   - Populate `npsp__Matching_Gift__c` on the employee's donation
   - Create an OCR on the Matching Gift opportunity with role "Matched Donor" for the employer contact
   - Create an `npsp__Partial_Soft_Credit__c` record if the match is partial
5. Verify the OCR and Partial Soft Credit records were created correctly on the Matching Gift opportunity.
6. Trigger rollup recalculation for the employer Contact.

**Why not the alternative:** Do not manually create an OCR with role "Soft Credit" on the employee's original gift to give the employer credit — this is incorrect model usage and will not behave correctly with NPSP rollups or reporting.

---

## Decision Guidance

| Situation | Recommended Approach | Reason |
|---|---|---|
| Household member should receive credit when spouse donates | Verify NPSP auto-soft-credit is enabled for household members; no manual OCR needed | NPSP creates household soft credit OCRs automatically; manual intervention causes duplicates |
| Board member cultivated the gift; should receive soft credit for the full amount | Add OCR with soft credit role; no Partial_Soft_Credit__c needed | Full-amount OCR-based soft credit is standard; partial record is only needed when the amount differs |
| Employer matching 50% of employee gift | Create Matching Gift opportunity on employer; use Find Matched Gifts; verify Partial_Soft_Credit__c amount is 50% | Matching gifts use a separate opportunity + partial soft credit — not a direct OCR on the donor gift |
| Soft credit total on Contact is $0 after adding OCR | Trigger manual rollup recalculation or wait for nightly batch | Rollup fields are not real-time for soft credits |
| Duplicate OCR records after Find Matched Gifts | Remove duplicate OCRs and Partial_Soft_Credit__c records manually; document as platform bug | Known bug when one contact has multiple gifts against the same Matching Gift opportunity |
| Need to give two contacts partial credit summing to 100% | Create an OCR for each contact, then a Partial_Soft_Credit__c record for each with the correct split amount | NPSP uses Partial_Soft_Credit__c amount (not OCR full amount) when partial records exist |

---

## Recommended Workflow

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

1. **Identify the credit type:** Determine whether this is a household auto-credit, relationship-based soft credit, or matching gift scenario. Each uses a different mechanism and configuration path.
2. **Verify NPSP Contact Role settings:** In NPSP Settings > Contact Roles, confirm the role values being used are in the soft credit roles list. A role not on this list will not contribute to rollup totals regardless of OCR configuration.
3. **Create or verify OCR records:** For manual soft credits, add the contact to the Opportunity's Contact Roles related list with the correct soft credit role. For matching gifts, use Find Matched Gifts rather than manual OCR creation.
4. **Create Partial_Soft_Credit__c records if needed:** If the credited amount differs from the full opportunity amount, create an `npsp__Partial_Soft_Credit__c` record linking the OCR and specifying the correct amount. Confirm `npsp__Contact_Role_ID__c` is populated.
5. **Check for duplicate records (matching gifts only):** After running Find Matched Gifts, query the Matching Gift opportunity's Contact Roles and `npsp__Partial_Soft_Credit__c` records to confirm there are no duplicates. If duplicates exist, delete the extras before running rollup recalculation.
6. **Trigger rollup recalculation:** Navigate to NPSP Settings > Batch Processing and run Recalculate Rollups for the affected contacts, or use the Contact-level Recalculate button. Confirm the soft credit rollup fields reflect the expected totals after recalculation.
7. **Validate totals and reporting:** Spot-check the affected Contact records' soft credit rollup fields and run a NPSP report filtered by soft credit this year to confirm amounts are correct and not doubled.

---

## Review Checklist

Run through these before marking work in this area complete:

- [ ] NPSP Contact Role settings confirmed — soft credit role values are in the recognized list
- [ ] OCR records created with correct role; no duplicate OCRs on the same opportunity for the same contact
- [ ] `npsp__Partial_Soft_Credit__c` records created where the credited amount differs from full opportunity amount
- [ ] `npsp__Contact_Role_ID__c` on Partial_Soft_Credit__c records is populated and points to the correct OCR
- [ ] For matching gifts: Matching Gift opportunity exists on employer Account before Find Matched Gifts is run
- [ ] Rollup recalculation triggered manually and soft credit totals verified on affected Contact records
- [ ] No platform bug duplicate records left in place (check OCR count and Partial_Soft_Credit__c count on Matching Gift opportunity)

---

## Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. **Soft credit rollups are not real-time** — Adding an OCR or Partial_Soft_Credit__c record does not immediately update `npsp__Soft_Credit_This_Year__c` or related rollup fields. The fields refresh only during the nightly batch or manual recalculation. Admins often assume the fields are broken when they are simply stale.
2. **Find Matched Gifts creates duplicate records when a contact has multiple gifts** — If a single donor Contact has two or more Opportunity records that are both run through Find Matched Gifts against the same Matching Gift opportunity, NPSP creates duplicate OCR and Partial_Soft_Credit__c records on the Matching Gift opportunity. This inflates rollup totals for the employer and is a known platform bug without an automated fix — duplicates must be deleted manually.
3. **A Partial_Soft_Credit__c without npsp__Contact_Role_ID__c is silently ignored** — If the lookup to the OCR is missing, NPSP does not raise an error but also does not use the partial amount in rollup calculations. The full opportunity amount is used instead, overstating the credit.

See `references/gotchas.md` for the extended list.

---

## Output Artifacts

| Artifact | Description |
|---|---|
| OpportunityContactRole records | OCR records with correct soft credit role assigned to non-donor contacts on the Opportunity |
| npsp__Partial_Soft_Credit__c records | Partial credit records linking an OCR to a specific credited amount when less than the full opportunity amount applies |
| Rollup recalculation confirmation | Evidence (screenshot or query) that Contact soft credit rollup fields reflect accurate totals after batch or manual recalculation |
| Matching Gift opportunity | Separate Opportunity record on the employer Account, used as the vehicle for employer hard credit in matching gift scenarios |

---

## Related Skills

- `gift-entry-and-processing` — For the NPSP Gift Entry staging flow that creates the underlying Opportunity; soft credit OCR roles are assigned after the gift is processed, not during staging
- `npsp-household-accounts` — For understanding the household data model that drives automatic household member soft credits