Npsp Data Model

NPSP Data Model

Activate this skill when a practitioner needs to understand, query, or design around the Nonprofit Success Pack (NPSP) managed-package data model — covering the five distinct namespace prefixes, their objects, and the cross-object relationships that govern donations, payments, recurring gifts, relationships, affiliations, and fund allocations. NOT for the standard Salesforce data model, Financial Services Cloud, or Program Management Module (PMM).

Before Starting

Gather this context before working on anything in this domain:

• Confirm NPSP is installed: check the Installed Packages list for "Nonprofit Success Pack" or query npe01__Households_Settings__c. If absent, none of the namespace-prefixed objects exist.
• Most common wrong assumption: practitioners and LLMs both assume all NPSP objects use the npsp__ prefix. In reality NPSP uses five distinct namespace prefixes and using the wrong one silently returns zero rows from SOQL without an error.
• Key limits in play: GAU Allocation records are not owned by the Opportunity via a master-detail; they are lookup-related, so deleting an Opportunity does NOT cascade-delete its allocations. Orphaned npsp__Allocation__c records cause reconciliation and reporting errors.

Core Concepts

The Five Namespace Prefixes

NPSP ships as a set of related managed packages, each with its own namespace:

Every Apex, SOQL, or metadata reference must use the exact namespace prefix for the object being referenced. Using npsp__OppPayment__c instead of npe01__OppPayment__c returns no results and no error.

GAU Allocations Are Lookups, Not Master-Detail

npsp__Allocation__c records relate to Opportunity via a lookup field (npsp__Opportunity__c), not a master-detail relationship. This has two important consequences:

1. Deleting an Opportunity does NOT cascade-delete its associated npsp__Allocation__c records. Orphaned allocations remain and can distort GAU reporting.
2. When cloning or migrating Opportunities, allocation records must be explicitly cloned or deleted. The standard Salesforce clone operation does not copy related lookup records.

When writing delete or migration logic touching Opportunities, always query and handle related npsp__Allocation__c records explicitly.

Recurring Donations and Installment Opportunities

npe03__Recurring_Donation__c drives a schedule-based process that auto-creates child Opportunity "installments." These installment Opportunities carry a lookup back to the parent npe03__Recurring_Donation__c via the npe03__Recurring_Donation__c lookup field on Opportunity (a custom field added by NPSP).

Direct creation of installment Opportunities without a parent recurring donation bypasses NPSP's schedule-tracking logic and breaks rollup fields on Contact (npe03__TotalOppAmount__c) and Account. Always create the parent npe03__Recurring_Donation__c first and let NPSP generate installments, or use NPSP's provided Apex APIs to create them programmatically with the correct parent reference.

Relationship and Affiliation Objects

npe4__Relationship__c is a junction object between two Contacts. It carries reciprocal relationship types (e.g., Spouse, Colleague). NPSP auto-creates mirror relationship records in both directions; deleting one mirror record triggers deletion of the other.

npe5__Affiliation__c links a Contact to a non-household Account, tracking role, dates, and primary affiliation status. It is distinct from the standard AccountContactRelationship object; the two coexist but serve different purposes.

Common Patterns

Querying GAU Allocations for a Set of Opportunities

When to use: Reporting or migration tasks that need to know how an Opportunity's revenue is split across General Accounting Units.

How it works:

SELECT Id, npsp__Amount__c, npsp__Percent__c,
       npsp__General_Accounting_Unit__c,
       npsp__General_Accounting_Unit__r.Name,
       npsp__Opportunity__c
FROM npsp__Allocation__c
WHERE npsp__Opportunity__c IN :opportunityIds

Why not the alternative: A subquery from Opportunity does not work because the relationship is a lookup (not master-detail). You must query npsp__Allocation__c directly and filter by Opportunity.

Querying Active Recurring Donations and Their Installments

When to use: Auditing open recurring gifts, identifying donors with active giving schedules, or migrating recurring donation data.

How it works:

-- Step 1: Get active recurring donations
SELECT Id, Name, npe03__Amount__c, npe03__Date_Established__c,
       npe03__Installment_Period__c, npe03__Contact__c,
       npe03__Organization__c
FROM npe03__Recurring_Donation__c
WHERE npe03__Open_Ended_Status__c = 'Open'

-- Step 2: Get installment Opportunities for a recurring donation
SELECT Id, Name, Amount, StageName, CloseDate,
       npe03__Recurring_Donation__c
FROM Opportunity
WHERE npe03__Recurring_Donation__c = :rdId
ORDER BY CloseDate ASC

Why not the alternative: Do not query Opportunities by a naming convention or date range alone to find installments. Always use the npe03__Recurring_Donation__c lookup field to anchor the query to the parent record.

Decision Guidance

Recommended Workflow

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

1. Confirm NPSP installation — verify the org has NPSP installed by checking the Installed Packages list or running SELECT Id FROM npe01__Households_Settings__c LIMIT 1. Do not proceed with namespace-prefixed references in an org without NPSP.
2. Identify the correct namespace prefix — use the five-prefix reference table to confirm which namespace owns the object you are working with. Never assume npsp__ is correct for all objects.
3. Check for cross-object lookup relationships — for GAU Allocations, confirm that deleting or migrating the parent Opportunity requires explicit handling of related npsp__Allocation__c records.
4. For recurring donation work — confirm whether the task involves the parent npe03__Recurring_Donation__c, its child installment Opportunities, or both. Always maintain the parent-child lookup to preserve rollup integrity.
5. Write and test SOQL with exact API names — use Workbench or Developer Console to validate the query returns expected results before embedding it in Apex or a flow.
6. Review output artifacts — confirm all generated API names, field references, and relationship traversals use the correct namespace and match the actual org schema.
7. Run the checker script — execute python3 scripts/check_npsp_data_model.py --manifest-dir <path> to scan metadata files for namespace errors and missing parent relationships.

Review Checklist

Run through these before marking work in this area complete:

• All NPSP object API names use the correct namespace prefix (not uniformly npsp__)
• Any code or query touching Opportunity deletion also handles related npsp__Allocation__c records
• Installment Opportunities are created with a valid npe03__Recurring_Donation__c parent reference
• Relationship and affiliation objects (npe4__, npe5__) are not confused with each other or with standard AccountContactRelationship
• SOQL queries are validated against actual org metadata before use in production Apex or flows
• GAU allocation percentages or amounts are confirmed to sum correctly per Opportunity before deployment

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Wrong namespace prefix returns zero rows silently — using npsp__OppPayment__c instead of npe01__OppPayment__c in SOQL produces no error and returns an empty result set. This is the most common source of "why is my query returning nothing?" bugs in NPSP orgs.
2. Opportunity delete does not cascade to GAU Allocations — npsp__Allocation__c is linked via a lookup, not master-detail. Orphaned allocations continue to accumulate and corrupt GAU reporting until explicitly cleaned up.
3. Direct installment Opportunity creation breaks rollups — NPSP rolls up total giving to Contact and Account via fields like npe01__TotalOppAmount__c. Creating Opportunities without the npe03__Recurring_Donation__c lookup populated bypasses the recurring donation schedule and produces incorrect rollup values.
4. Mirror relationship deletion is bidirectional — deleting one npe4__Relationship__c record triggers NPSP automation to delete the reciprocal mirror record. Bulk deleting relationship records via Data Loader can cause double-count errors on delete batches.
5. Affiliation primary flag is org-wide scoped per Contact — npe5__Primary__c on npe5__Affiliation__c is managed by NPSP automation. Setting it directly in DML during data loads can trigger NPSP's affiliation process, which sets and unsets primary flags on other affiliations for the same contact.

Output Artifacts

Official Sources Used

• NPSP Data Model Gallery — https://developer.salesforce.com/docs/nonprofit/npsp/guide/npsp-data-model.html
• NPSP Objects and Fields Data Dictionary — https://help.salesforce.com/s/articleView?id=sfdo.NPSP_Objects_and_Fields_Data_Dictionary.htm&type=5
• Trailhead: Explore the NPSP Data Model — https://trailhead.salesforce.com/content/learn/modules/nonprofit-success-pack-basics/explore-the-npsp-data-model

Related Skills

• admin/npsp-household-accounts — household account configuration and the npo02__ namespace for household rollup fields
• admin/npsp-program-management — PMM data model (ServiceDelivery__c, Program__c); distinct from NPSP donation objects
• data/fsc-data-model — Financial Services Cloud data model; FinServ__ namespace is entirely separate from NPSP namespaces