Historical Giving: Import Order, Mappings, Fulfillments, and Updating

Importing giving history into Slate is not just a matter of loading gifts. Gifts, pledges, planned gifts, opportunities, soft credits, tributes, and related records can all connect to one another. The order in which those records are imported determines whether Slate can create those relationships correctly.

This article explains how to plan giving imports, how pledge and planned gift fulfillments work, how Slate determines whether to create or update records, and how to structure files for both historical giving imports and later corrections or updates.

For detailed guidance on a specific import type, see:

• Importing Relationships
• Importing Opportunities and Opportunity Notes
• Importing Planned Gifts
• Importing Pledges
• Importing Gifts
• Importing Soft Credits
• Importing Tribute and Occasion Gifts

Overview

Giving imports generally fall into two categories:

These workflows use many of the same Upload Dataset mapping destinations, but they require different planning.

For historical giving imports, the key question is: What must already exist before this row can connect to it?

For update imports, the key question is: How will Slate know which existing record this row should update?

Recommended Historical Import Order

For historical giving migrations, the recommended order is:

1. Constituent records
2. Relationships
3. Opportunities
4. Opportunity notes
5. Pledges
6. Planned gifts
7. Gifts
8. Soft credits

This order allows later records to reference records that already exist.

Some records can be combined into a single upload when the file is intentionally structured that way, but separate files are usually easier to validate, troubleshoot, and re-run.

Constituent Matching Comes First

Before Slate can create or update a giving record, it must first resolve the constituent record for the row.

Constituent matching values are mapped separately from giving values.

This distinction matters when building import mappings. The constituent match tells Slate which person, company, foundation, or other record the row belongs to. After that record is resolved, Slate can create or update the giving record for that constituent.

For historical imports, institutions often use a legacy constituent ID stored in a custom field marked Unique for Merging. In that case, the matching destination appears under the Fields dropdown/category, not under the giving categories.

Use External IDs for Giving Records

Whenever possible, include an External ID for each imported opportunity, pledge, planned gift, gift, and soft credit.

External IDs are strongly recommended because they make future imports easier. They can be used to:

• Update records after the initial import.
• Connect gifts to pledges or planned gifts.
• Connect gifts, pledges, or planned gifts to opportunities.
• Add soft credits to existing gifts.
• Correct missing or incorrect relationships.
• Reverse existing gifts.

For historical imports, External IDs are usually more useful than Slate-generated identities because the Slate identities will not exist until after the records are created.

If the legacy system does not provide a unique ID for a giving record, create one before import using a stable combination of values, such as legacy constituent ID, gift date, gift amount, transaction ID, fund ID, or another reliable source value.

How Slate Decides Whether to Create or Update

After the constituent record is resolved, Slate evaluates the giving record mappings.

For gifts, pledges, and planned gifts, Slate attempts to match an existing record using available matching values such as:

1. Slate GUID
2. Identity
3. External ID

In this context, Identity refers to the Slate-generated identity for the giving record, not an ID from the legacy system.

When a match is found, Slate updates the existing record. When no match is found, Slate may create a new record if the row contains the required values for that record type, such as the required gift fields for a gift import.

For update imports, always include a reliable matching value. Otherwise, the row may create a duplicate instead of updating the intended record.

Creating Records vs. Updating Existing Records

Historical imports and update imports should be structured differently.

Creating Records

Use an import to bring records into Slate for the first time.

A creation file should include:

• A way to match the row to the correct constituent.
• The required fields for the record being created.
• An External ID for future updates.
• Identifiers for related records that already exist.

Examples include:

• Creating opportunities.
• Creating pledges.
• Creating planned gifts.
• Creating gifts.
• Creating gifts that fulfill existing pledges or planned gifts.
• Creating soft credits after the hard credit gifts exist.

Updating Existing Records

Use an import to update records that already exist in Slate.

An update file should include:

• A way to match the row to the correct constituent.
• A way to match the existing giving record.
• Only the fields or actions you intend to apply.

Examples include:

• Adding External IDs to existing records.
• Correcting dates, campaigns, appeals, notes, or other values.
• Connecting an existing gift to an existing pledge or planned gift.
• Adding soft credits to existing gifts.
• Adding or replacing tribute/honoring information.
• Reversing existing gifts.

When updating, do not map fields you do not intend to change.

For gift updates in particular, be careful when mapping the full set of required gift creation values. If the gift matching value does not resolve to an existing gift on the resolved constituent record, and the row contains enough values to create a gift, Slate can create a new gift instead of updating the intended one.

Understanding Upload Dataset Mapping Categories

Upload Dataset mapping categories are organized around the object being created, updated, or connected. This may not always match how users describe the business process.

For example, if a gift fulfills a pledge, the fulfillment mapping appears under Giving - Gift because the gift is the record being imported or updated. Even though the business process is “fulfilling a pledge,” the mapped value is applied to the gift.

The category answers the question: What object is this value being applied to?

Recommended File Structures

The examples below are starting points. Specific files may include more columns depending on the institution’s data and business process.

The “Recommended File Structures” section explains what columns are commonly useful. The “Common Import Scenarios” section later in this article shows example spreadsheet-style rows.

Opportunities File

Use this file before importing giving records that should connect to opportunities.

Recommended columns:

For more detail, see Importing Opportunities and Opportunity Notes.

Opportunity Notes File

Use this file to add historical notes to existing opportunities.

Recommended columns:

Opportunity notes are imported through Opportunity Log destinations.

Pledges File

Use this file before importing gifts that fulfill pledges.

Recommended columns:

Use one row per pledge unless the source file is intentionally structured with multiple pledge ordinals.

For more detail, see Pledge Mapping Destinations.

Planned Gifts File

Use this file before importing gifts that fulfill planned gifts.

Recommended columns:

For more detail, see Importing Planned Gifts.

Gifts File

Use this file to import outright gifts and gifts that fulfill pledges or planned gifts.

Recommended columns:

Use one row per gift unless the source file is intentionally structured with multiple gift ordinals.

For more detail, see Importing Gifts.

Soft Credits File

Use this file when adding standalone soft credits to gifts that already exist.

Recommended columns:

For more detail, see Soft Credit Mapping Destinations.

Understanding Fulfillments

A fulfillment is the connection between a received gift and an earlier commitment, such as a pledge or planned gift.

When a gift fulfills a pledge or planned gift, Slate connects the received gift to the original commitment. Slate then uses that connection to calculate received and remaining amounts.

For example:

1. A donor makes a $10,000 pledge.
2. The pledge is imported with Pledge External ID = P-1001.
3. A later $2,500 gift is imported with Fulfilled Pledge External ID = P-1001.
4. Slate connects the gift to the pledge.
5. The pledge’s received and remaining amounts are recalculated.

Fulfillment is mapped from the gift import because the gift is the record being created or updated.

Fulfillment Mapping Options

Recommended Approach: Use External IDs

For most historical migrations:

1. Import pledges and planned gifts first.
2. Include External IDs on those records.
3. Import gifts later.
4. Include the fulfilled pledge or planned gift External ID in the gift file.
5. Map that value to the gift fulfillment destination.

This approach is easier to review and troubleshoot than relying on same-row mapping.

Same-Ordinal Fulfillment

Same-ordinal fulfillment is useful for files where each row contains both the commitment and the payment that fulfills it.

Example source row:

In this structure:

• Pledge fields are mapped at ordinal 1.
• Gift fields are mapped at ordinal 1.
• The gift fulfillment same-ordinal destination is mapped.
• Slate creates or stages the pledge and connects the gift to it in the same import process.

This method should be used only when the relationship between the pledge or planned gift and the gift is clear and consistent in the source file.

For large historical imports, separate files using External IDs are usually easier to validate.

What Happens When Fulfillment Matching Fails

If a gift references a pledge or planned gift that Slate cannot find, the gift can still import as a standalone received gift without the fulfillment connection.

A successful gift import therefore does not always mean the fulfillment relationship was created.

Common causes include:

• The pledge or planned gift was not imported first.
• The External ID in the gift file does not exactly match the External ID on the pledge or planned gift.
• The wrong identifier type was mapped.
• The pledge or planned gift belongs to a different constituent.
• Same-ordinal mapping was used, but the pledge or planned gift and gift were not mapped at the same ordinal.

Always review fulfillments after import.

What Slate Does Automatically After Fulfillment

When a gift is connected to a pledge or planned gift, Slate recalculates related giving totals.

For pledges, this includes received and remaining amounts. If the pledge or gift is connected to an opportunity, opportunity totals may also update based on the connected giving records.

If the gift is missing certain values, Slate may inherit values from the fulfilled pledge or planned gift where appropriate. For example, a fulfilling gift may inherit values such as fund, campaign, appeal, opportunity, or anonymous status from the commitment if those values are not provided directly on the gift row.

Recommended practice: include values explicitly on the gift row when they should differ from the pledge or planned gift.

Pledge Installments

Pledge installments can be generated during pledge import when the file includes the necessary installment values.

At minimum, the file should include:

If installment count or duration is missing, installments are not generated.

Soft Credits

Soft credits can be created in two general ways:

1. Standalone soft credit imports.
2. Soft credits generated during a gift, pledge, or planned gift import.

Standalone Soft Credit Imports

Use standalone soft credit imports when the hard credit gift already exists and the source system provides explicit soft credit records.

The file should identify:

• The donor record that owns the hard credit gift.
• The hard credit gift, sometimes referred to as the base gift in import matching.
• The record receiving soft credit.
• The soft credit amount, if different from the hard credit gift amount.

Relationship-Based Soft Credits

Relationship-based soft credits can be applied during gift, pledge, or planned gift import.

Slate supports relationship-based soft credit behavior based on relationship prompt settings:

Relationship-based soft credits depend on relationships and relationship prompt settings already being configured. Load and review relationships before importing giving records that rely on this behavior.

Explicit Soft Credit Targeting

Soft credits can also be targeted explicitly during giving import.

Supported targeting can include:

Custom Unique Fields and Related-Record Linking

Slate identifiers and custom unique fields can both be used for matching and related-record linking, but they appear in different parts of the mapping interface and serve different purposes.

Custom unique fields can be used in three important ways:

The practical rule is:

Use the Record category for Slate identifiers. Use the Fields dropdown/category for custom fields configured as Unique for Merging.

Tributes and Honoring

Tribute and honoring data can be imported alongside gifts, pledges, and planned gifts.

A tribute or honoring import may identify:

• A linked Slate record being honored.
• A free-text honoree name.
• An occasion, such as In Honor Of or In Memory Of.
• Multiple tribute records on the same gift, pledge, or planned gift.

Recommended columns include:

When importing multiple tributes for a single giving record, use the appropriate grouping or subgrouping structure in the mapping interface so Slate knows which tribute record, honoree text, and occasion belong together.

For more detail, see Importing Tribute and Occasion Gifts.

Gift Reversals

Gift reversal is an action taken against an existing gift.

A reversal import does not create a new gift that is already reversed. Instead, Slate finds an existing gift and creates the reversal activity for that gift.

To reverse gifts through import:

1. Include a reliable constituent matching value.
2. Include a reliable gift matching value, such as Gift External ID, Gift Identity, or Gift GUID.
3. Map the reversal value to the gift reversal destination.
4. Confirm that the matched gift is not already reversed.

Important behavior:

• If the row does not match an existing gift, the reversal row is skipped.
• If the gift is already reversed, the row is skipped.
• A soft credit row cannot be reversed as though it were a hard credit gift.
• Soft credits connected to the original gift may be affected by the reversal process.

Recommended practice: use a dedicated reversal file that contains only rows intended to reverse existing gifts.

Example reversal file:

Common Import Scenarios

Full Historical Giving Migration

Recommended workflow:

1. Import constituents and organizations.
2. Import relationships.
3. Import opportunities with External IDs.
4. Import opportunity notes.
5. Import pledges with External IDs and opportunity references.
6. Import planned gifts with External IDs and opportunity references.
7. Import gifts with External IDs and fulfillment references.
8. Import standalone soft credits.
9. Review results by phase.

This approach is easiest to validate because each phase creates records that the next phase can reference.

Import Gifts That Fulfill Existing Pledges

Use this workflow when pledges already exist in Slate.

Example gift file:

Mapping approach:

• Resolve the constituent using the Record category or Fields dropdown/category.
• Map gift values under Giving - Gift.
• Map the fulfilled pledge External ID to the gift fulfillment destination.
• Review the pledge after import to confirm the gift is connected.

Import Pledges and Gifts From the Same Source Row

Use this workflow when the legacy file contains pledge and payment information in the same row.

Example combined pledge and gift file:

Mapping approach:

• Map the constituent legacy ID using the appropriate field under the Fields dropdown/category.
• Map pledge fields under Giving - Pledge at ordinal 1.
• Map gift fields under Giving - Gift at ordinal 1.
• Use same-ordinal fulfillment so the gift fulfills the pledge in the same row.

Use this approach only when the source file has a clear one-to-one relationship between the pledge or planned gift and the fulfilling gift in that row.

Add Soft Credits to Existing Gifts

Use this workflow when gifts already exist and you need to add explicit soft credits.

Example soft credit file:

Mapping approach:

• Resolve the donor record.
• Match the hard credit gift.
• Identify the soft credit recipient.
• Include an amount override only when the soft credit amount should differ from the hard credit gift amount.

Update Existing Gifts

Use this workflow when gifts already exist and values need to be corrected.

Example gift update file:

Mapping approach:

• Match the constituent.
• Match the existing gift.
• Map only the fields you intend to update.
• Validate a small test file before applying bulk corrections.

Connect Existing Gifts to Existing Pledges

Use this workflow when both the gift and pledge already exist, but the fulfillment relationship was not created during the original import.

Example fulfillment correction file:

Mapping approach:

• Match the existing gift.
• Map the pledge External ID to the gift fulfillment destination.
• Review the pledge to confirm received and remaining amounts recalculated.

Reverse Existing Gifts

Use this workflow when existing gifts need to be reversed.

Example reversal file:

Mapping approach:

• Match the existing gift.
• Map the reversal flag.
• Review results to confirm the reversal was created.

Reviewing Results After Import

Review each phase before moving to the next one.

After Opportunity Import

Confirm:

• Expected opportunity count.
• Opportunity summaries, statuses, dates, and amounts.
• External IDs are populated.
• Opportunities appear on the correct records.

After Pledge Import

Confirm:

• Pledges appear on the correct constituent records.
• Amount, fund, status, type, and date are correct.
• Opportunity links are present where expected.
• Installments were generated where expected.
• External IDs are populated.

After Planned Gift Import

Confirm:

• Planned gifts appear on the correct constituent records.
• Amount, fund, status, type, date, revocable, and anonymous values are correct.
• Opportunity links are present where expected.
• External IDs are populated.

After Gift Import

Confirm:

• Gifts appear on the correct constituent records.
• Amount, fund, status, type, and date are correct.
• Gifts that should fulfill pledges or planned gifts are connected.
• Fulfilled pledges show updated received and remaining amounts.
• Opportunity, campaign, appeal, tribute, and honoring values are correct.
• Relationship-based soft credits were applied only where intended.

After Soft Credit Import

Confirm:

• Soft credits appear on the correct hard credit gifts.
• The correct records received soft credit.
• Amount overrides are correct.
• Duplicate soft credits were not created.

After Update or Reversal Imports

Confirm:

• The intended existing records were updated.
• No unintended duplicates were created.
• Reversals applied only to the intended gifts.
• Already-reversed gifts were not processed again.
• Related totals and reporting reflect the changes.

Troubleshooting

Gifts Imported, But They Did Not Fulfill Pledges

Check:

• Was the pledge imported before the gift?
• Does the pledge have the External ID used in the gift file?
• Was the correct fulfillment destination mapped?
• Does the pledge belong to the same constituent as the gift?
• If using same ordinal, are the pledge and gift mapped at the same ordinal?

A New Gift or Giving Record Was Created Instead of Updating an Existing Record

Check:

• Was a matching identifier mapped?
• Did the matching value resolve to a record on the resolved constituent?
• Is the matching value correct and free of leading or trailing spaces?
• Did the row include enough required values to create a new record when the match failed?
• For gift updates, did the file include the full set of required gift creation values?

Soft Credits Were Not Created

Check:

• Does the hard credit gift already exist?
• Does the gift identifier match the hard credit gift?
• Does the soft credit recipient identifier resolve to a valid record?
• Are you trying to soft-credit the same record that owns the hard credit gift?
• If using relationship-based soft credits, are relationships and relationship prompt settings configured correctly?
• If using custom unique fields, is the field configured as Unique for Merging and populated consistently?

Opportunity Links Are Missing

Check:

• Was the opportunity imported first?
• Does the opportunity have the External ID used in the giving file?
• Does the opportunity belong to the same record or an eligible related record?
• Was the opportunity mapping destination used under the correct giving category?

Pledge Installments Were Not Created

Check:

• Was installment count mapped?
• Was months between installments mapped?
• Are both values greater than zero?
• Was the installment start date provided, or should the pledge date be used?

Tribute or Honoring Information Is Missing

Check:

• Was the giving record matched or created successfully?
• Was the tribute or honoring record identifier mapped correctly?
• If using a custom unique field, is the field configured as Unique for Merging?
• Were group/subgroup values used correctly for multiple tributes?
• Was the occasion value valid?

Reversal Rows Were Skipped

Check:

• Did the row match an existing gift?
• Is the matched gift already reversed?
• Is the row trying to reverse a soft credit rather than a hard credit gift?
• Was the reversal flag mapped correctly?

Recommended Practices

1. Import in phases.
   Separate files make it easier to confirm each record type before the next phase depends on it.

2. Use External IDs for giving records.
   External IDs are the most practical way to support future updates, corrections, and fulfillment mapping.

3. Understand where matching values appear.
   Slate IDs and record-level identifiers appear in the Record category. Custom fields marked Unique for Merging appear in the Fields dropdown/category.

4. Keep creation files and update files separate.
   Creation files usually include required fields. Update files should focus on matching identifiers and the specific values being changed.

5. Do not map values you do not intend to change.
   When updating existing records, keep the file focused.

6. Test with a small sample.
   Use a small, representative file before running a large historical import or correction import.

7. Review after each phase.
   Confirm that records exist, identifiers are populated, and relationships were created before importing the next dependent file.

8. Use custom unique fields intentionally.
   Custom unique fields can resolve primary records and connect related records such as soft credits and tributes, but only when they are configured and populated consistently.

9. Treat reversals as a separate workflow.
   Reversal imports should target existing gifts. They should not be mixed into general new-gift imports unless carefully tested.

Summary

Giving imports work best when they are planned around relationships.

For historical imports, create the records that other records depend on first: opportunities before giving records, pledges and planned gifts before fulfilling gifts, and gifts before standalone soft credits.

For update imports, the matching identifier is the most important value. Slate must be able to identify the existing record before it can update values, add relationships, or reverse a gift.

A well-structured import includes reliable constituent matching, External IDs for giving records, the required fields for creation, and clear identifiers for related records. By importing in phases, validating each phase, and using stable identifiers, administrators can preserve giving history and reduce the risk of duplicate or disconnected records.