Gift Data Mapping

This document details the field-level mappings between WeGive transaction records and Blackbaud Raiser’s Edge NXT gift records.

Object Overview

WeGive Transaction Object

Purpose: Represents donations and payments processed through WeGive platform
API Endpoint: /transactions/{transaction}
Unique Identifier: WeGive transaction ID
Payment Processing: Includes payment method, status, and processing details

Blackbaud Gift Object

Purpose: Represents donations, pledges, and other contributions in Raiser’s Edge NXT
API Endpoint: gift/v1/gifts/{gift_id}
Unique Identifier: Blackbaud gift ID
Financial Management: Includes fund designations, recognition, and stewardship

Core Gift Mapping

Basic Gift Information

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`id`	Correlation ID storage	String	Both	No	Stored in custom field or reference
`amount`	`amount.value`	Decimal	Both	Yes	Gift amount in dollars
`currency`	`amount.currency`	String	Both	No	Default “USD”
`created_at`	`date`	DateTime	Both	Yes	Gift date, timezone converted
`status`	Gift status	String	Both	No	Completed, Pending, Failed
`reference_number`	`reference`	String	Both	No	External reference or check number

Donor and Constituency

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`owner.id`	`constituent_id`	String	Both	Yes	Links to constituent record
`owner.type`	Derived from constituent	String	Both	No	Individual or Organization
`owner.name`	Derived from constituent	String	Both	No	Display name for gift

Payment Method Mapping

WeGive Payment Method	Blackbaud Payment Method	Description
`card`	`CreditCard`	Credit and debit card payments
`bank`	`DirectDebit`	Bank transfers and ACH
`check`	`PersonalCheck`	Physical and electronic checks
`cash`	`Cash`	Cash donations
`wire`	`WireTransfer`	Wire transfers
`paypal`	`OnlinePayment`	PayPal and digital wallets
`venmo`	`OnlinePayment`	Venmo and peer-to-peer payments
`other`	`Other`	Other payment methods

Gift Type Classification

WeGive Transaction Type	Blackbaud Gift Type	Sub Type	Notes
`donation`	`Donation`	`Cash`	Standard one-time donation
`recurring`	`RecurringGiftPayment`	`Pledge`	Payment from recurring schedule
`pledge_payment`	`PledgePayment`	`Installment`	Payment toward pledge commitment
`grant`	`Grant`	`Foundation`	Foundation or institutional grant
`tribute`	`Donation`	`Memorial`	Memorial or honor gift
`matching`	`MatchingGift`	`Corporate`	Corporate matching gift

Fund Designation Mapping

Single Fund Designation

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`fund.id`	`designations[0].fund_id`	String	Both	Yes	Primary fund designation
`fund.name`	`designations[0].fund.name`	String	Both	No	Fund display name
`amount`	`designations[0].amount`	Decimal	Both	Yes	Full gift amount to single fund

Multiple Fund Designations

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`fund_allocations`	`designations`	Array	Both	No	Multiple fund splits
`fund_allocations[].fund_id`	`designations[n].fund_id`	String	Both	Yes	Fund identifier
`fund_allocations[].amount`	`designations[n].amount`	Decimal	Both	Yes	Allocated amount
`fund_allocations[].percentage`	Calculated	Decimal	Both	No	Percentage of total gift

Example Multi-Fund Gift Structure (Blackbaud)

{
  "amount": {"value": 100.00, "currency": "USD"},
  "designations": [
    {
      "fund_id": "fund-123",
      "amount": {"value": 75.00, "currency": "USD"}
    },
    {
      "fund_id": "fund-456", 
      "amount": {"value": 25.00, "currency": "USD"}
    }
  ]
}

Campaign and Appeal Attribution

Campaign Tracking

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`campaign.id`	`appeals[0].campaign_id`	String	Both	No	Primary campaign attribution
`campaign.name`	`appeals[0].campaign.name`	String	Both	No	Campaign display name
`appeal.id`	`appeals[0].id`	String	Both	No	Specific appeal within campaign
`appeal.name`	`appeals[0].name`	String	Both	No	Appeal display name

Marketing Attribution

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`source`	`source_code`	String	Both	No	Marketing source tracking
`medium`	Custom attribute	String	Both	No	Marketing medium
`utm_campaign`	Custom attribute	String	Both	No	UTM campaign parameter
`utm_source`	Custom attribute	String	Both	No	UTM source parameter
`utm_medium`	Custom attribute	String	Both	No	UTM medium parameter

Gift Recognition and Acknowledgment

Acknowledgment Preferences

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`anonymous`	`anonymous`	Boolean	Both	No	Anonymous gift preference
`no_thank_you`	`do_not_acknowledge`	Boolean	Both	No	Skip acknowledgment
`tribute_type`	`tribute.type`	String	Both	No	Memorial, Honor, Celebration
`tribute_name`	`tribute.name`	String	Both	No	Person being honored/remembered

Stewardship Information

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`thank_you_sent`	`acknowledged`	Boolean	Both	No	Acknowledgment status
`thank_you_date`	`acknowledge_date`	Date	Both	No	When thank you was sent
`tax_receipt_sent`	`receipted`	Boolean	Both	No	Tax receipt status
`tax_receipt_date`	`receipt_date`	Date	Both	No	When receipt was issued
`tax_deductible_amount`	`receipt_amount`	Decimal	Both	No	Deductible portion

Soft Credits and Recognition

Soft Credit Tracking

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`soft_credits`	`soft_credits`	Array	Both	No	Additional recognition credits
`soft_credits[].constituent_id`	`soft_credits[n].constituent_id`	String	Both	Yes	Person receiving soft credit
`soft_credits[].amount`	`soft_credits[n].amount`	Decimal	Both	No	Soft credit amount
`soft_credits[].type`	`soft_credits[n].type`	String	Both	No	Solicitor, Volunteer, etc.

Joint Gift Recognition

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`joint_donors`	Additional constituents	Array	Both	No	Multiple donors for single gift
`primary_donor`	Primary constituent	String	Both	Yes	Main donor for gift record
`joint_recognition`	Recognition credits	Array	Both	No	Recognition for all donors

Recurring Gift Integration

Recurring Gift Schedule

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`recurring_donation_id`	`recurring_gift_id`	String	Both	No	Links to recurring gift schedule
`installment_number`	`installment`	Integer	Both	No	Sequence number in series
`total_installments`	Derived from schedule	Integer	Both	No	Total expected payments

Pledge Integration

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`pledge_id`	`pledge_id`	String	Both	No	Links to pledge commitment
`pledge_balance`	Calculated	Decimal	Both	No	Remaining pledge balance
`pledge_payment_number`	`installment`	Integer	Both	No	Payment sequence number

Processing and Financial Details

Transaction Processing

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`processor`	`payment_method_details`	String	Both	No	Payment processor used
`processor_fee`	`fees`	Decimal	Both	No	Processing fees
`net_amount`	`net_amount`	Decimal	Both	No	Amount after fees
`processor_reference`	`external_reference`	String	Both	No	Processor transaction ID

Bank and Check Details

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`check_number`	`check_number`	String	Both	No	Physical check number
`check_date`	`check_date`	Date	Both	No	Date on check
`bank_name`	`bank_name`	String	Both	No	Bank name for check
`routing_number`	`routing_number`	String	Both	No	Bank routing number
`account_number`	`account_number`	String	Both	No	Masked account number

Custom Fields and Attributes

Gift Attributes

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`custom_fields`	`attributes`	Object	Both	No	Organization-specific fields
`tags`	`gift_codes`	Array	Both	No	Gift categorization codes
`notes`	`notes`	Array	Both	No	Free-form text notes
`internal_notes`	`internal_notes`	Array	Both	No	Staff-only notes

Event and Fundraiser Integration

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`event_id`	`event_id`	String	Both	No	Associated event or fundraiser
`table_purchase`	`event_participation`	Object	Both	No	Event table or ticket details
`sponsorship_level`	`sponsorship`	String	Both	No	Sponsorship tier

Data Transformation Rules

Amount Handling

Currency Conversion

All amounts stored in dollars (USD) by default
Multi-currency support available
Exchange rates captured at time of gift
Historical rate preservation for reporting

Precision Rules

Dollar amounts rounded to 2 decimal places
Large gifts (>$1M) maintain full precision
Fee calculations preserve all decimal places
Percentage calculations rounded to 4 places

Date and Time Processing

Timezone Handling

Gift dates stored in donor’s local timezone when available
UTC conversion for cross-system compatibility
Daylight saving time adjustments applied
Historical date preservation for reporting

Date Field Mapping

created_at → Gift date (when gift was made)
processed_at → Process date (when gift was processed)
deposited_at → Deposit date (when funds were deposited)

Status Mapping

WeGive Status	Blackbaud Status	Description
`completed`	`Active`	Successfully processed gift
`pending`	`Pending`	Gift awaiting processing
`failed`	`Inactive`	Failed or rejected gift
`refunded`	`Reversed`	Refunded or reversed gift
`disputed`	`Held`	Disputed or under review

Sync Behavior

Create Operations

New WeGive Transaction → Blackbaud Gift

Validate gift data and requirements
Map payment method and amount
Link to existing constituent
Apply fund designations
Create gift record in Blackbaud
Store correlation ID for future updates
Process any soft credits or attributions

New Blackbaud Gift → WeGive Transaction

Extract gift and constituent information
Map to WeGive transaction format
Create or link to WeGive donor
Preserve fund and campaign attributions
Store correlation ID

Update Operations

Bidirectional Updates

Gift amount and designation changes
Payment method updates
Recognition and acknowledgment status
Notes and attribute modifications
Soft credit additions or changes

Restricted Updates

Gift date typically immutable after creation
Constituent linkage requires administrative approval
Major amount changes may require audit trail
Status changes follow business rules

Delete and Void Operations

Gift Reversal

WeGive refunds create reversed gift records
Blackbaud gift reversals update status
Audit trail preserved for all changes
Financial reporting adjustments applied

API Examples

Create Gift Record

WeGive to Blackbaud Gift Creation

POST /gift/v1/gifts
{
  "constituent_id": "280bb97a-f71e-4158-9040-85506f6c2e8e",
  "type": "Donation",
  "subtype": "Cash",
  "amount": {
    "value": 250.00,
    "currency": "USD"
  },
  "date": "2024-03-15T10:30:00Z",
  "payment_method": "CreditCard",
  "designations": [
    {
      "fund_id": "f1e8c4a7-2b5d-4c91-8e72-1a3b4c5d6e7f",
      "amount": {
        "value": 250.00,
        "currency": "USD"
      }
    }
  ],
  "appeals": [
    {
      "campaign_id": "c123-4567-8901-2345",
      "appeal_id": "a987-6543-2109-8765"
    }
  ],
  "reference": "WG-TXN-123456"
}

Update Gift Acknowledgment

Blackbaud to WeGive Acknowledgment Sync

PUT /transactions/{transaction_id}
{
  "thank_you_sent": true,
  "thank_you_date": "2024-03-20T14:00:00Z",
  "tax_receipt_sent": true,
  "tax_receipt_date": "2024-03-20T14:00:00Z",
  "tax_deductible_amount": 250.00,
  "blackbaud_gift_id": "12345678-1234-1234-1234-123456789abc"
}

Multi-Fund Gift Example

Complex Gift with Multiple Designations

{
  "amount": {"value": 1000.00, "currency": "USD"},
  "designations": [
    {
      "fund_id": "general-fund",
      "amount": {"value": 600.00, "currency": "USD"},
      "percentage": 60.0
    },
    {
      "fund_id": "building-fund", 
      "amount": {"value": 300.00, "currency": "USD"},
      "percentage": 30.0
    },
    {
      "fund_id": "scholarship-fund",
      "amount": {"value": 100.00, "currency": "USD"},
      "percentage": 10.0
    }
  ],
  "soft_credits": [
    {
      "constituent_id": "spouse-id",
      "amount": {"value": 1000.00, "currency": "USD"},
      "type": "Joint Gift Credit"
    }
  ]
}

Error Handling and Validation

Required Field Validation

Critical Fields

Constituent ID must exist and be valid
Gift amount must be positive
Gift date cannot be in the future
At least one fund designation required
Payment method must be valid type

Data Quality Checks

Amount precision validation (2 decimal places)
Date format validation (ISO 8601)
Currency code validation (3-letter codes)
Fund ID existence verification
Constituent relationship validation

Common Error Scenarios

Invalid Constituent

Error: Constituent ID not found
Resolution: Create constituent first or use valid ID
Action: Queue gift for manual review

Fund Validation Errors

Error: Fund ID invalid or inactive
Resolution: Map to default fund or create fund
Action: Log warning and use fallback fund

Amount Validation Issues

Error: Negative or zero amount
Resolution: Skip transaction or flag for review
Action: Log error and notify administrators

Retry and Recovery Logic

Temporary Failures

Network timeouts: Retry with exponential backoff
Rate limiting: Respect retry-after headers
Server errors: Retry up to 3 times with increasing delays

Permanent Failures

Validation errors: Log and skip record
Authorization errors: Alert system administrators
Data conflicts: Queue for manual resolution

Performance Optimization

Batch Processing

Gift Creation Batches

Process up to 100 gifts per API call
Group by constituent for efficiency
Parallel processing for independent gifts
Progress tracking and status reporting

Update Optimization

Delta sync for changed records only
Timestamp-based change detection
Bulk update operations where supported
Minimized API calls through intelligent batching

Caching Strategies

Reference Data Caching

Fund information cached for 1 hour
Campaign data cached for 30 minutes
Constituent lookups cached for 15 minutes
Payment method mappings cached indefinitely

Performance Monitoring

Average gift sync time tracking
API response time monitoring
Error rate alerting
Throughput optimization

Reporting and Analytics

Gift Analytics

Sync Metrics

Total gifts synchronized per period
Success/failure rates by gift type
Average sync time per gift
Peak processing times

Data Quality Metrics

Validation error rates
Missing required field frequency
Fund mapping accuracy
Constituent linking success rates

Financial Reconciliation

Amount Reconciliation

Total gift amounts by period
Currency conversion accuracy
Fee calculation validation
Multi-fund designation accuracy

Audit Trail Maintenance

Complete change history
User attribution for modifications
System-generated change timestamps
Compliance audit support

Best Practices

Data Management

Clean Source Data: Validate transaction data before sync
Consistent Mapping: Maintain standardized fund and campaign mapping
Regular Reconciliation: Compare financial totals between systems
Backup Strategy: Maintain gift data backups before major changes

Performance Optimization

Batch Operations: Use batch processing for bulk gift imports
Rate Limiting: Respect API limits and implement proper throttling
Caching: Cache frequently accessed reference data
Monitoring: Track sync performance and optimize bottlenecks

Security and Compliance

Data Encryption: Encrypt sensitive gift data in transit and at rest
Access Control: Limit gift data access to authorized personnel
Audit Logging: Maintain comprehensive audit trails
Compliance: Follow PCI DSS and other applicable regulations

Troubleshooting Guide

Common Sync Issues

Gift Creation Failures

Verify constituent exists in both systems
Check fund ID validity and active status
Validate gift amount and currency format
Confirm payment method mapping accuracy

Amount Discrepancies

Review currency conversion rates
Check fee calculation methods
Validate multi-fund designation totals
Verify decimal precision handling

Date and Time Issues

Confirm timezone settings
Check date format compliance
Validate date range restrictions
Review daylight saving time handling

Data Quality Problems

Missing Gift Data

Check field mapping completeness
Verify data availability in source system
Review sync scope and filtering rules
Validate required field population

Incorrect Attribution

Review campaign and appeal mapping
Check fund designation accuracy
Validate soft credit assignments
Confirm marketing source attribution

Performance Issues

Slow Gift Processing

Optimize batch sizes for gift volume
Review API response times
Check network connectivity
Monitor system resource usage

High Error Rates

Analyze error pattern trends
Review data validation rules
Check system capacity limits
Validate integration configuration

Support Resources

Documentation References

Support Contacts

WeGive Support: [email protected]
Blackbaud Developer Support: Developer Community
Integration Specialists: Available for complex gift mapping scenarios

Overview

Data Mapping

​Gift Data Mapping

​Object Overview

​WeGive Transaction Object

​Blackbaud Gift Object

​Core Gift Mapping

​Basic Gift Information

​Donor and Constituency

​Payment Method Mapping

​Gift Type Classification

​Fund Designation Mapping

​Single Fund Designation

​Multiple Fund Designations

​Campaign and Appeal Attribution

​Campaign Tracking

​Marketing Attribution

​Gift Recognition and Acknowledgment

​Acknowledgment Preferences

​Stewardship Information

​Soft Credits and Recognition

​Soft Credit Tracking

​Joint Gift Recognition

​Recurring Gift Integration

​Recurring Gift Schedule

​Pledge Integration

​Processing and Financial Details

​Transaction Processing

​Bank and Check Details

​Custom Fields and Attributes

​Gift Attributes

​Event and Fundraiser Integration

​Data Transformation Rules

​Amount Handling

​Date and Time Processing

​Status Mapping

​Sync Behavior

​Create Operations

​Update Operations

​Delete and Void Operations

​API Examples

​Create Gift Record

​Update Gift Acknowledgment

​Multi-Fund Gift Example

​Error Handling and Validation

​Required Field Validation

​Common Error Scenarios

​Retry and Recovery Logic

​Performance Optimization

​Batch Processing

​Caching Strategies

​Reporting and Analytics

​Gift Analytics

​Financial Reconciliation

​Best Practices

​Data Management

​Performance Optimization

​Security and Compliance

​Troubleshooting Guide

​Common Sync Issues

​Data Quality Problems

​Performance Issues

​Support Resources

​Documentation References

​Support Contacts

Gift Data Mapping

Object Overview

WeGive Transaction Object

Blackbaud Gift Object

Core Gift Mapping

Basic Gift Information

Donor and Constituency

Payment Method Mapping

Gift Type Classification

Fund Designation Mapping

Single Fund Designation

Multiple Fund Designations

Campaign and Appeal Attribution

Campaign Tracking

Marketing Attribution

Gift Recognition and Acknowledgment

Acknowledgment Preferences

Stewardship Information

Soft Credits and Recognition

Soft Credit Tracking

Joint Gift Recognition

Recurring Gift Integration

Recurring Gift Schedule

Pledge Integration

Processing and Financial Details

Transaction Processing

Bank and Check Details

Custom Fields and Attributes

Gift Attributes

Event and Fundraiser Integration

Data Transformation Rules

Amount Handling

Date and Time Processing

Status Mapping

Sync Behavior

Create Operations

Update Operations

Delete and Void Operations

API Examples

Create Gift Record

Update Gift Acknowledgment

Multi-Fund Gift Example

Error Handling and Validation

Required Field Validation

Common Error Scenarios

Retry and Recovery Logic

Performance Optimization

Batch Processing

Caching Strategies

Reporting and Analytics

Gift Analytics

Financial Reconciliation

Best Practices

Data Management

Performance Optimization

Security and Compliance

Troubleshooting Guide

Common Sync Issues

Data Quality Problems

Performance Issues

Support Resources

Documentation References

Support Contacts