Updating Existing Records

Use the reference_id field to update records that already exist in CauseVox. This works for donations, pledges, installments, and contacts. It's useful for correcting data or syncing with external systems.

How It Works

When you process a batch:

1. The system checks if a record with that reference_id already exists
2. If found: The existing record is updated with the new data
3. If not found: A new record is created

This makes batch imports idempotent - you can safely re-import the same data without creating duplicates.

Setting Up Reference IDs

For New Records

When creating records, include a unique reference_id:

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-001,John Smith,100.00,USD,2024-01-15,abc123-def456
DON-002,Jane Doe,250.00,USD,2024-01-16,abc123-def456

Best Practices for Reference IDs

• Use your external system's ID (e.g., from your old CRM)
• Create a consistent naming convention (e.g., DON-2024-001)
• Keep them unique across all donations or pledges
• Store them in your spreadsheet for future reference

TIP

If you don't provide a reference_id, the system generates one automatically. However, you won't be able to update that record via batch import later.

---

What Gets Updated

When updating an existing record, not all fields are updated. This protects important relationships and prevents data corruption.

Donations & Pledges

Fields That WILL Update

These fields are updated when you re-import a donation or pledge with a matching reference_id:

Category	Fields
Basic Info	display_name, amount, currency_code, created_at
Donor Details	first_name, last_name, email, company_name
Address	line1, line2, city, state, zipcode, country
Associations	campaign_id, donation_form_id, site_id, project_id, team_id, network_id
Settings	anonymous, anonymous_type, comment
Tribute Info	tribute_type, tribute_honoree_name
Revenue Payment	revenue_status, revenue_payment_method, revenue_payment_channel, revenue_payment_reference, revenue_payment_meta
Tags	Added if not already present (safe to re-import)
Custom Fields	Replaced with new values on each import
Contact Link	contact_id (only if explicitly provided)

Fields That Will NOT Update

These fields are skipped for existing records to prevent duplicates:

Field	Why It's Skipped
Revenue splits	Only created on initial import. Re-importing does not add, remove, or modify splits.
Revenue credits	Only created on initial import. Re-importing does not add, remove, or modify credits.
Tribute soft credits	Only created on initial import to prevent duplicates.
Auto-contact creation	Existing records already have contact handling.

Important

If a donation already has a contact linked and you re-import without specifying contact_id, the existing contact link is preserved. We don't automatically create a new contact for existing records.

Installments

Fields That WILL Update

Category	Fields
Basic Info	amount, created_at
Revenue Payment	revenue_status, revenue_payment_method, revenue_payment_channel, revenue_payment_reference, revenue_payment_meta
Tags	Added if not already present (safe to re-import)
Custom Fields	Replaced with new values on each import

Fields That Will NOT Update

Field	Why It's Skipped
Revenue splits	Only created on initial import. Re-importing does not add, remove, or modify splits.
Revenue credits	Only created on initial import. Re-importing does not add, remove, or modify credits.

Contacts

Fields That WILL Update

Category	Fields
Basic Info	display_name, title, first_name, middle_name, last_name, suffix, maiden_name, deceased, can_contact
Primary Email	email, email_can_contact (upserts existing primary email)
Primary Phone	phone, phone_can_call, phone_can_text (upserts existing primary phone)
Primary Address	line1, line2, city, state, zipcode, country, address_can_contact (upserts existing primary address)
Tags	Added if not already present (safe to re-import)
Custom Fields	Replaced with new values on each import

TIP

Non-primary contact methods (secondary emails, phones, addresses) are not affected by re-imports.

---

Example: Updating Records

Scenario 1: Correct an Amount

Original import:

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-001,John Smith,100.00,USD,2024-01-15,abc123-def456

Correction import:

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-001,John Smith,150.00,USD,2024-01-15,abc123-def456

Result: The existing donation's amount changes from $100 to $150.

Scenario 2: Add Missing Information

Original import (minimal data):

reference_id,display_name,amount,currency_code,created_at,campaign_id
DON-002,Jane Doe,250.00,USD,2024-01-16,abc123-def456

Update with more details:

reference_id,display_name,amount,currency_code,created_at,campaign_id,email,city,state
DON-002,Jane Doe,250.00,USD,2024-01-16,abc123-def456,jane@example.com,Boston,MA

Result: Email and address are added to the existing donation.

Scenario 3: What Doesn't Change

If you import a record that exists but include different tribute information:

reference_id,display_name,amount,tribute_type,tribute_honoree_name,...
DON-001,John Smith,150.00,in_memory_of,Robert Smith,...

Result:

• The tribute_type and tribute_honoree_name fields ARE updated
• BUT a new tribute soft credit is NOT created (that only happens for new records)

---

Re-Importing Data Safely

Step 1: Export Your Existing Data

Before re-importing, export your current data as a backup.

Step 2: Include Reference IDs

Make sure your import file has the same reference_ids as existing records.

Step 3: Review Changes

After importing, check a few records to verify updates applied correctly.

---

When to Use Updates vs. New Records

Use Case	Approach
Correcting typos or amounts	Update (same reference_id)
Adding missing information	Update (same reference_id)
Recording a new donation	New (new or no reference_id)
Migrating from another system	New with reference_ids from old system
Syncing with external system	Update (use external system's IDs)

---

Troubleshooting

"I updated but nothing changed"

• Verify the reference_id matches exactly (case-sensitive)
• Check that the record type matches (donation vs. pledge)
• Confirm the record was processed (not just added to batch)

"A new record was created instead of updating"

• The reference_id didn't match an existing record
• Check for typos or extra spaces in the reference_id
• The original record might not have had a reference_id set

"Contact wasn't updated"

• For existing records, contact is only updated if you explicitly provide contact_id
• Auto-contact creation only happens for new records