SfSkills Domains Docs GitHub

Home / admin / gift-entry-and-processing

gift-entry-and-processing

Configure and operate NPSP Gift Entry: gift entry templates, batch gift entry, payment processing, donation allocation, and receipting workflows. NOT for a one-time migration of historical gift data — use data/gift-history-import. NOT for soft credits or matching gifts — use admin/soft-credits-and-matching.

Open the skill folder on GitHub

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:

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:

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:

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

SituationRecommended ApproachReason
Single gift entered by a fundraiserDefault Gift Entry TemplateOnly template type that supports single-entry UI
Bulk gifts from a mailer or eventCustom batch template + Batch Gift EntryBatch templates support multi-record grid; batch processing is more efficient
Validating before committing a large batchprocessGiftEntries with isDryRun=trueCatches field mapping and allocation errors without any DB commits
Receipting for tax purposesTaxReceiptStatus on GiftTransaction (API v62.0+)Platform-native receipt status tracking; integrates with downstream receipt flows
Org is on API < v62.0Custom receipt status field on GiftTransactionTaxReceiptStatus not available; document the workaround in a skill note
Advanced Mapping not yet enabledEnable Advanced Mapping in NPSP Settings firstGift Entry feature activation blocked without it

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:

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

ArtifactDescription
Active Default Gift Entry TemplateConfigured single-entry template with required fields and payment options
Custom Batch Gift Entry TemplateBatch-only template linked to a campaign or fiscal period
processGiftEntries invocation patternDocumented dry-run and commit invocation sequence with error handling
GiftTransaction recordsPromoted donation records with designation and soft credit allocations
TaxReceiptStatus configurationReceipting status field wired to downstream automation (API v62.0+ orgs)

Package files