The Hidden Reason Most NPSP Migrations Break (And It's Not What You Think)

Imagine moving house and sending the furniture to the new address before the building exists. That's what happens when donation records land in Agentforce Nonprofit before the donor records they belong to have arrived.

It sounds obvious. And yet it's the single biggest reason NPSP-to-AFNP migrations produce broken, incomplete, or orphaned data — and in almost every case, it was entirely preventable.

What "Referential Integrity" Actually Means

In Salesforce, records don't exist in isolation — they point to each other. A donation points to a donor. A payment points to a gift. A soft credit points to both a gift and a contact.

Referential integrity means every record that references another record can actually find the thing it's pointing to. When it's intact, your data makes sense — a fundraiser can pull up a donor and see their full giving history. When it's broken, records float free with no owner, and your data becomes noise.

Every parent record must exist before its children arrive. Not a best practice — a hard constraint.

What It Looks Like When It Breaks

The dangerous part is that a broken migration often looks fine at first. Record counts match. No error messages. Then, three weeks later:

• Donations show no donor name — listed as "Unknown"
• Monthly giving schedules exist with no linked contact, so direct debits process but can't be attributed
• Soft credits point to contacts that don't exist yet, and never surface in donor summaries
• Finance reports on total donated vs. total committed don't reconcile — and nobody knows why

This isn't just a data quality problem. Gift acknowledgment letters, tax receipts, and donor stewardship all depend on connected data. An orphaned donation is a gift your system knows about but can't attribute to anyone.

Why AFNP Makes This Harder, Not Easier

NPSP and Agentforce Nonprofit run on the same platform but organise data very differently — and that difference is exactly where migrations go wrong.

Accounts and Contacts. In NPSP, individual donors are Contacts under a Household Account. In AFNP, they become Person Accounts — Account and Contact merged into one record. Your contact base has to be split into household and organisation groups, each loaded after its parent account exists.

Recurring Donations become three objects. In NPSP, one record holds the whole relationship. In AFNP, it's a Gift Commitment (the donor relationship), a Gift Commitment Schedule (frequency, dates, amount), and Gift Transactions (every payment already made) — each dependent on the one before it. Load these out of order and you get payment history with nowhere to attach.

One Opportunity type becomes four target objects. Depending on whether a donation was multi-payment, single-payment, still open, or refunded, it needs to land as a Gift Commitment, Gift Transaction, Opportunity, or Gift Refund — each with its own dependency chain.

Get any of these sequences wrong, and the fix isn't a quick patch. It's weeks of manual reconciliation, or worse, donor data that's quietly wrong for a year before anyone notices.

The Three Failures We See Most Often

1. Loading contacts before accounts, because it "feels" like the right place to start. Contacts with no parent account either get rejected or lose their household relationship entirely.
2. Treating recurring donations as a single object. The commitment and schedule have to exist before a single payment transaction can link to them. Skip that, and your monthly giving report comes back blank.
3. No clean way to resume after a failed batch. A network timeout mid-load leaves teams choosing between re-running from scratch (duplicates) or manually figuring out what actually landed.

Checking Whether Your Data Arrived Intact

If you've already migrated — or you're about to — these are the checks that tell you the truth:

• Contact and Person Account counts match your NPSP source exactly
• No Opportunities with a null Account and null Primary Contact
• Every Gift Transaction links to either a Gift Commitment or a Contact
• Every Gift Commitment has a corresponding Gift Commitment Schedule
• Total Gift Transactions reconcile against total Closed Won Opportunities in NPSP
• Every soft credit references a valid Contact and a valid Gift Transaction

The strongest migrations also keep an External ID (e.g. NPSP_Source_ID__c) on every AFNP record, tracing it back to its NPSP original — a complete audit trail if anything ever needs investigating.

Why This Is Genuinely Hard to Do by Hand

A careful team could sequence this manually — the same way a careful team could hand-count a large election. Technically possible, catastrophically error-prone, and unnecessary.

The real cost of manual sequencing isn't malice or incompetence — it's human error at scale. A single step out of order, a batch that runs early, and referential integrity breaks silently, in ways that surface weeks later when a major donor calls about their giving history.

We've Done This the Hard Way — So You Don't Have To

We've run enough NPSP-to-AFNP migrations to know exactly where referential integrity breaks, and we built AFNP Migration Agent to automate all the migration efforts and load all the data in the correct load order automatically — parent objects before children, recurring gifts sequenced correctly across Commitment, Schedule, and Transaction, checkpointed so a failed batch never means starting over, and every step logged for a full audit trail.

If you're planning a migration to Agentforce Nonprofit — or you've already started and something doesn't reconcile — talk to us. We'll tell you exactly what shape your data is in before anything moves.

Explore Zenyus

Continue your Salesforce and nonprofit digital transformation journey with our tools, stories, and resources.

AI for Nonprofits Toolkit

Free guides, prompts, and playbooks for nonprofit teams.

Learn more

Success Stories

See how Australian nonprofits transformed with Salesforce.

Learn more

AFNP Compass

Scan your org before migrating to Agentforce for Nonprofit.

Learn more

AFNP Migration Agent

Automated NPSP to Agentforce for Nonprofit migration.

Learn more