Gift Entry and Processing

This skill activates when a practitioner needs to configure, troubleshoot, or extend the NPSP Gift Entry feature — covering template setup, batch entry, the staging-to-target promotion pipeline via processGiftEntries, payment processing, donation allocation, and receipt tracking. It does NOT cover direct Opportunity creation or manual DML against GiftTransaction outside the Gift Entry framework.

---

Before Starting

Gather this context before working on anything in this domain:

• Advanced Mapping must be enabled. Navigate to NPSP Settings > Advanced Mapping and enable it before attempting to activate the Gift Entry feature. Gift Entry will not activate without it.
• API version constraint. The GiftEntry staging object is available at API v59.0+. The TaxReceiptStatus field on GiftTransaction is available at API v62.0+. Verify the org's API version before relying on these.
• Template type constraint. The Default Gift Entry Template is the only template that supports single-gift entry in the standard Gift Entry UI. Custom templates are batch-only. This is a hard platform constraint, not a configuration choice.
• Common wrong assumption: practitioners assume Gift Entry writes directly to Opportunity or GiftTransaction via DML. In reality, it creates a GiftEntry staging record first, and the processGiftEntries invocable action performs the promotion.

---

Core Concepts

Staging Object: GiftEntry

Every gift submitted through Gift Entry creates a GiftEntry__c (or GiftEntry in API v59.0+ schema) staging record. This record holds all raw gift data — donor, amount, payment method, designations — before the data is validated and committed to target objects. The staging record persists until processGiftEntries is explicitly called. If that action is never invoked, the gift lives only in staging and no GiftTransaction, GiftDesignation, or GiftSoftCredit record is ever created.

processGiftEntries Invocable Action

processGiftEntries is the platform action that promotes a GiftEntry staging record to its target records:

• GiftTransaction — the canonical donation record
• GiftDesignation — maps the gift amount to one or more fund/program allocations
• GiftSoftCredit — assigns soft credit to relationships (e.g., household members)

The action accepts an isDryRun parameter. When isDryRun=true, it validates the staging record against all rules and field mappings without committing anything. This is the correct pre-processing gate for large batches. When isDryRun=false (default), it commits the records.

Gift Entry Templates

Templates define the fields, sections, payment options, and allocations presented to gift entry users. Two template contexts exist:

• Default Gift Entry Template — system-provided; supports single-gift entry in the standard UI; cannot be deleted; customizable but not replaceable for single-entry mode.
• Custom templates — administrator-created; batch-only; define a layout and field set specific to a campaign, fiscal period, or entry team.

Activating the Gift Entry feature requires at minimum that the Default Gift Entry Template is active.

TaxReceiptStatus and Receipting

TaxReceiptStatus on GiftTransaction tracks whether a tax receipt has been issued, is pending, or is not applicable. This field is only available at API v62.0+. Orgs on earlier API versions should use a custom field or a separate receipting object.

---

Common Patterns

Pattern 1: Single-Gift Entry with Dry Run Validation

When to use: A frontline fundraiser is entering one gift at a time, and the org wants validation before committing.

How it works:

1. User opens Gift Entry, selects the Default Gift Entry Template.
2. Fills in donor, amount, payment method, and designation fields.
3. Staff clicks "Validate" — this triggers processGiftEntries with isDryRun=true in the background.
4. Errors (missing required fields, invalid payment method, allocation mismatch) surface immediately.
5. Staff corrects errors, then clicks "Process" — processGiftEntries runs with isDryRun=false.
6. GiftTransaction, GiftDesignation, and optionally GiftSoftCredit records are created.

Why not direct DML: Writing directly to Opportunity or GiftTransaction bypasses Advanced Mapping field mappings, skips designation logic, and prevents receipt tracking via TaxReceiptStatus.

Pattern 2: Batch Gift Entry for Year-End Processing

When to use: Finance team processes hundreds of mailed checks at fiscal year-end.

How it works:

1. Admin creates a custom batch template scoped to the year-end campaign.
2. Staff opens Batch Gift Entry, selects the custom template, enters all gifts in the batch grid.
3. Before submitting, runs a dry-run pass via processGiftEntries with isDryRun=true across all staged records — surfaces any issues.
4. Fixes flagged records in the grid.
5. Submits the batch — processGiftEntries runs in sequence for each staging record.
6. All promoted GiftTransaction records have TaxReceiptStatus set to PENDING for downstream receipt generation.

Why not a data load: Direct imports via Data Loader bypass Gift Entry entirely. They produce raw GiftTransaction records without GiftDesignation allocation logic and without the Advanced Mapping field transformations.

---

Decision Guidance

Situation	Recommended Approach	Reason
Single gift entered by a fundraiser	Default Gift Entry Template	Only template type that supports single-entry UI
Bulk gifts from a mailer or event	Custom batch template + Batch Gift Entry	Batch templates support multi-record grid; batch processing is more efficient
Validating before committing a large batch	processGiftEntries with isDryRun=true	Catches field mapping and allocation errors without any DB commits
Receipting for tax purposes	TaxReceiptStatus on GiftTransaction (API v62.0+)	Platform-native receipt status tracking; integrates with downstream receipt flows
Org is on API < v62.0	Custom receipt status field on GiftTransaction	TaxReceiptStatus not available; document the workaround in a skill note
Advanced Mapping not yet enabled	Enable Advanced Mapping in NPSP Settings first	Gift Entry feature activation blocked without it

---

Recommended Workflow

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

1. Verify prerequisites. Confirm NPSP is installed, Advanced Mapping is enabled (NPSP Settings > Advanced Mapping), and the org is on API v59.0+. If Advanced Mapping is off, enable it before proceeding — Gift Entry activation will fail otherwise.
2. Activate Gift Entry. In NPSP Settings > Gift Entry, toggle the feature on. Confirm the Default Gift Entry Template is listed as active.
3. Configure the Default Gift Entry Template for single-gift entry. Add required fields (donor lookup, amount, payment method, fund designation), configure payment gateway if applicable, and save.
4. Create a custom batch template if batch entry is needed. Set the template name, batch entry fields, allocation default, and link to the relevant campaign or fund.
5. Test with isDryRun=true. Submit a test staging record and invoke processGiftEntries with isDryRun=true. Confirm validation messages match expectations and no target records are created.
6. Process and verify target records. Run processGiftEntries with isDryRun=false on the test record. Confirm GiftTransaction, GiftDesignation, and GiftSoftCredit records are created with correct field values per Advanced Mapping rules.
7. Configure receipting. If on API v62.0+, set the default TaxReceiptStatus value on processed GiftTransaction records and wire up any receipt automation.

---

Review Checklist

Run through these before marking work in this area complete:

• Advanced Mapping is enabled in NPSP Settings
• Default Gift Entry Template is active and has required fields configured
• Custom batch templates (if any) are batch-only and correctly scoped
• processGiftEntries dry-run pass executes without errors on test staging records
• processGiftEntries full-run creates GiftTransaction, GiftDesignation, and GiftSoftCredit records
• TaxReceiptStatus is set on GiftTransaction records (API v62.0+ only; document workaround if on earlier version)
• No GiftEntry staging records remain in a permanently unprocessed state after testing

---

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Advanced Mapping gate — Gift Entry feature activation silently fails or produces an error if Advanced Mapping has never been enabled. Many practitioners skip this step assuming NPSP installs with it on by default. It does not. Enable it first, every time.
2. Staging records persist if processGiftEntries is never called — There is no automatic cleanup of GiftEntry staging records. If an integration or custom flow creates staging records but never invokes processGiftEntries, the gifts accumulate in staging indefinitely and never appear as GiftTransactions in reporting.
3. Default template is the only single-entry template — Attempting to use a custom template for single-gift entry produces no UI entry point. Custom templates surface only in Batch Gift Entry. This is a hard constraint, not a missing configuration.
4. isDryRun does not roll back — it never commits — isDryRun=true is a validation-only pass; it does not create records and does not need a rollback. Some practitioners apply transaction guards around dry-run calls, which adds no value and can introduce lock contention.
5. TaxReceiptStatus API version dependency — Querying TaxReceiptStatus on GiftTransaction in orgs below API v62.0 returns an "invalid field" error. Always check the org's API version before referencing this field in Apex, Flow, or SOQL.

---

Output Artifacts

Artifact	Description
Active Default Gift Entry Template	Configured single-entry template with required fields and payment options
Custom Batch Gift Entry Template	Batch-only template linked to a campaign or fiscal period
processGiftEntries invocation pattern	Documented dry-run and commit invocation sequence with error handling
GiftTransaction records	Promoted donation records with designation and soft credit allocations
TaxReceiptStatus configuration	Receipting status field wired to downstream automation (API v62.0+ orgs)

---

Related Skills

• recurring-donations-setup — Configure NPSP recurring donations, which feed staging records into Gift Entry differently than one-time gifts
• npsp-data-model — Understand the full NPSP object graph that Gift Entry writes into
• gift-entry-and-processing is the upstream step before any care-program-management or financial reporting workflows that consume GiftTransaction records