Recurring Gift Data Mapping

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

Object Overview

WeGive Recurring Donation Object

Purpose: Represents recurring/subscription donations in the WeGive platform
API Endpoint: /recurring_donations/{recurring_donation}
Unique Identifier: WeGive recurring donation ID
Payment Processing: Automated recurring payment collection

Blackbaud Recurring Gift Object

Purpose: Represents recurring gifts and pledges in Raiser’s Edge NXT
API Endpoint: gift/v1/recurringgifts/{recurring_gift_id}
Unique Identifier: Blackbaud recurring gift ID
Stewardship Management: Donor commitment tracking and recognition

Core Recurring Gift Mapping

Basic Recurring Gift Information

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`id`	Correlation ID storage	String	Both	No	Stored in custom field or external reference
`amount`	`amount.value`	Decimal	Both	Yes	Recurring gift amount per installment
`currency`	`amount.currency`	String	Both	No	Default “USD”
`frequency`	`frequency`	String	Both	Yes	Payment frequency
`status`	`status`	String	Both	No	Active, Inactive, Cancelled, Completed
`start_date`	`start_date`	Date	Both	Yes	First payment date
`end_date`	`end_date`	Date	Both	No	Final payment date (if specified)

Donor and Constituency

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

Payment Schedule Configuration

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`frequency`	`frequency`	String	Both	Yes	Payment interval
`day_of_month`	`day_of_month`	Integer	Both	No	Specific day for monthly payments
`day_of_week`	`day_of_week`	String	Both	No	Specific day for weekly payments
`installments`	`installments`	Integer	Both	No	Total number of payments
`installments_paid`	`installments_paid`	Integer	Both	No	Payments completed to date

Frequency Mapping

WeGive Frequency	Blackbaud Frequency	Description
`weekly`	`Weekly`	Every 7 days
`biweekly`	`Every two weeks`	Every 14 days
`monthly`	`Monthly`	Once per month
`quarterly`	`Quarterly`	Every 3 months
`semiannual`	`Semiannually`	Every 6 months
`annual`	`Annually`	Once per year
`custom`	`Other`	Custom frequency with specified interval

Status Mapping

WeGive Status	Blackbaud Status	Description
`active`	`Active`	Currently processing payments
`paused`	`Held`	Temporarily suspended
`cancelled`	`Terminated`	Cancelled by donor or system
`completed`	`Completed`	All installments processed
`failed`	`Lapsed`	Failed due to payment issues
`expired`	`Expired`	Ended due to expiration date

Fund Designation and Campaign Attribution

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 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 per payment
`fund_allocations[].percentage`	Calculated	Decimal	Both	No	Percentage of total gift

Campaign and Appeal Attribution

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
`source`	`source_code`	String	Both	No	Marketing source tracking

Payment Method and Processing

Payment Method Information

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`payment_method.type`	`payment_method`	String	Both	Yes	Credit card, bank transfer, etc.
`payment_method.last_four`	`payment_details`	String	Both	No	Last 4 digits of payment method
`payment_method.brand`	`card_type`	String	Both	No	Visa, MasterCard, etc.
`payment_method.expires`	`expiration_date`	Date	Both	No	Payment method expiration

Payment Method Mapping

WeGive Payment Method	Blackbaud Payment Method	Description
`card`	`CreditCard`	Credit and debit cards
`bank`	`DirectDebit`	Bank transfers and ACH
`paypal`	`OnlinePayment`	PayPal recurring payments
`check`	`PersonalCheck`	Recurring check commitments

Processing Configuration

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`processor`	`payment_processor`	String	Both	No	Payment processor used
`processor_fee_percentage`	`processing_fee_rate`	Decimal	Both	No	Fee percentage per transaction
`auto_retry_failed`	`retry_failed_payments`	Boolean	Both	No	Automatic retry on failures
`max_retries`	`max_retry_attempts`	Integer	Both	No	Maximum retry attempts

Pledge Integration

Pledge Relationship

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`pledge_id`	`pledge_id`	String	Both	No	Associated pledge commitment
`pledge_type`	`commitment_type`	String	Both	No	Recurring vs. one-time pledge
`pledge_balance`	`balance_remaining`	Decimal	Both	No	Remaining commitment balance
`pledge_payment_schedule`	`payment_schedule`	Object	Both	No	Scheduled payment dates

Commitment Tracking

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`commitment_amount`	`total_committed`	Decimal	Both	No	Total commitment value
`commitment_date`	`commitment_date`	Date	Both	No	Date commitment was made
`expected_completion`	`projected_end_date`	Date	Both	No	Expected completion date
`completion_percentage`	Calculated	Decimal	Both	No	Percentage of commitment fulfilled

Gift History and Tracking

Payment History

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`payments`	`gifts`	Array	Both	No	Individual payment records
`first_payment_date`	`first_gift_date`	Date	Both	No	Date of first successful payment
`last_payment_date`	`last_gift_date`	Date	Both	No	Date of most recent payment
`next_payment_date`	`next_expected_date`	Date	Both	No	Next scheduled payment

Payment Statistics

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`total_paid`	`total_paid`	Decimal	Both	No	Total amount paid to date
`successful_payments`	`successful_gifts`	Integer	Both	No	Number of successful payments
`failed_payments`	`failed_attempts`	Integer	Both	No	Number of failed payment attempts
`average_payment`	Calculated	Decimal	Both	No	Average successful payment amount

Donor Communication and Stewardship

Communication Preferences

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`send_receipts`	`send_acknowledgments`	Boolean	Both	No	Send payment receipts
`receipt_frequency`	`acknowledgment_frequency`	String	Both	No	Per payment, monthly, annually
`thank_you_template`	`acknowledgment_template`	String	Both	No	Thank you message template
`special_instructions`	`stewardship_notes`	Text	Both	No	Special stewardship instructions

Recognition and Acknowledgment

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`anonymous`	`anonymous`	Boolean	Both	No	Anonymous recurring gift
`recognition_name`	`recognition_name`	String	Both	No	Name for recognition purposes
`honor_memorial`	`tribute`	Object	Both	No	Honor/memorial designation
`recognition_level`	`recognition_tier`	String	Both	No	Donor recognition level

Modification and Lifecycle Management

Recurring Gift Modifications

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`amount_changes`	`amount_adjustments`	Array	Both	No	History of amount changes
`frequency_changes`	`frequency_adjustments`	Array	Both	No	History of frequency changes
`pause_periods`	`suspension_periods`	Array	Both	No	Temporary suspension history
`modification_date`	`last_modified`	DateTime	Both	No	Date of last modification

Cancellation and Completion

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`cancellation_reason`	`termination_reason`	String	Both	No	Reason for cancellation
`cancellation_date`	`termination_date`	Date	Both	No	Date recurring gift ended
`completion_date`	`completion_date`	Date	Both	No	Date all installments completed
`final_payment_amount`	`final_gift_amount`	Decimal	Both	No	Amount of final payment

Custom Fields and Attributes

Extended Recurring Gift Information

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`custom_fields`	`attributes`	Object	Both	No	Organization-specific fields
`tags`	`recurring_gift_codes`	Array	Both	No	Categorization tags
`donor_notes`	`donor_comments`	Text	Both	No	Donor-provided notes
`internal_notes`	`internal_notes`	Text	Both	No	Staff-only notes

Sustainer Program Integration

WeGive Field	Blackbaud Field	Data Type	Direction	Required	Notes
`sustainer_program`	`sustainer_program_id`	String	Both	No	Associated sustainer program
`enrollment_date`	`program_enrollment_date`	Date	Both	No	Date enrolled in program
`program_benefits`	`member_benefits`	Array	Both	No	Program member benefits
`upgrade_opportunities`	`upgrade_prospects`	Array	Both	No	Potential upgrade opportunities

Data Transformation Rules

Amount and Financial Processing

Amount Handling

All amounts stored in dollars with 2 decimal precision
Currency conversion applied when necessary
Historical exchange rates preserved
Automatic rounding to nearest cent

Fee Calculations

Processing fees calculated per transaction
Fee structures updated automatically
Net amount calculations maintained
Cost tracking for ROI analysis

Schedule and Frequency Processing

Date Calculations

Next payment date calculated automatically
Business day adjustments for weekends/holidays
Leap year handling for annual recurring gifts
Timezone considerations for international donors

Frequency Conversions

Standard frequency mapping between systems
Custom frequencies converted to closest standard
Schedule adjustments for donor preferences
Grace periods for payment processing

Status and Lifecycle Management

Status Transitions

Automatic status updates based on payment success/failure
Business rules for status change permissions
Audit trail for all status modifications
Notification triggers for status changes

Sync Behavior

Create Operations

New WeGive Recurring Donation → Blackbaud Recurring Gift

Validate recurring gift data and requirements
Map payment method and schedule information
Link to existing constituent
Apply fund designations and campaign attribution
Create recurring gift record in Blackbaud
Store correlation ID for future updates
Initialize payment schedule

New Blackbaud Recurring Gift → WeGive Recurring Donation

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

Update Operations

Bidirectional Updates

Amount and frequency modifications
Fund designation changes
Status updates and lifecycle changes
Payment method updates
Schedule adjustments

Payment Processing Updates

Successful payment recording
Failed payment tracking
Retry attempt logging
Next payment date calculation

Cancellation and Completion Operations

Recurring Gift Termination

Status update to cancelled/completed
Final payment processing
Balance calculations and reconciliation
Historical data preservation
Stewardship transition planning

API Examples

Create Recurring Gift Record

WeGive to Blackbaud Recurring Gift Creation

POST /gift/v1/recurringgifts
{
  "constituent_id": "280bb97a-f71e-4158-9040-85506f6c2e8e",
  "amount": {
    "value": 50.00,
    "currency": "USD"
  },
  "frequency": "Monthly",
  "start_date": "2024-04-01",
  "day_of_month": 1,
  "status": "Active",
  "payment_method": "CreditCard",
  "designations": [
    {
      "fund_id": "f1e8c4a7-2b5d-4c91-8e72-1a3b4c5d6e7f",
      "amount": {
        "value": 50.00,
        "currency": "USD"
      }
    }
  ],
  "appeals": [
    {
      "campaign_id": "c123-4567-8901-2345",
      "appeal_id": "sustainer-program-2024"
    }
  ],
  "reference": "WG-REC-789012"
}

Update Recurring Gift Status

Payment Processing Status Update

PUT /recurring_donations/{recurring_donation_id}
{
  "status": "active",
  "installments_paid": 3,
  "total_paid": 150.00,
  "last_payment_date": "2024-06-01T10:30:00Z",
  "next_payment_date": "2024-07-01T10:30:00Z",
  "successful_payments": 3,
  "failed_payments": 0,
  "blackbaud_recurring_gift_id": "12345678-1234-1234-1234-123456789abc"
}

Recurring Gift with Multiple Designations

Multi-Fund Recurring Gift Example

{
  "amount": {"value": 100.00, "currency": "USD"},
  "frequency": "Monthly",
  "designations": [
    {
      "fund_id": "general-fund",
      "amount": {"value": 60.00, "currency": "USD"},
      "percentage": 60.0
    },
    {
      "fund_id": "scholarship-fund",
      "amount": {"value": 40.00, "currency": "USD"},
      "percentage": 40.0
    }
  ],
  "commitment_type": "Pledge",
  "total_committed": {"value": 1200.00, "currency": "USD"},
  "installments": 12,
  "acknowledgment_frequency": "Annually",
  "attributes": [
    {
      "attribute_category": "Sustainer Program",
      "string_value": "Monthly Heroes"
    },
    {
      "attribute_category": "Enrollment Channel",
      "string_value": "Website"
    }
  ]
}

Error Handling and Validation

Required Field Validation

Critical Fields

Constituent ID must exist and be valid
Amount must be positive
Frequency must be valid enumerated value
Start date cannot be in the past
At least one fund designation required

Data Quality Checks

Amount precision validation (2 decimal places)
Date format validation (ISO 8601)
Frequency value validation
Payment method validation
Fund ID existence verification

Common Error Scenarios

Invalid Constituent

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

Payment Method Errors

Error: Invalid or expired payment method
Resolution: Update payment method information
Action: Pause recurring gift until resolved

Schedule Validation Issues

Error: Invalid frequency or date combination
Resolution: Adjust to supported schedule
Action: Log warning and use closest valid schedule

Retry and Recovery Logic

Payment Processing Failures

Automatic retry logic for failed payments
Exponential backoff for retry attempts
Maximum retry limits with manual intervention
Payment method update notifications

Sync Failures

Network timeouts: Retry with exponential backoff
Rate limiting: Respect retry-after headers
Server errors: Retry up to 3 times with delays
Data conflicts: Queue for manual resolution

Performance Optimization

Batch Processing

Recurring Gift Management

Process payment schedules in batches
Group by payment date for efficiency
Parallel processing for independent operations
Progress tracking and status reporting

Payment Processing Optimization

Batch payment method validations
Group payment attempts by processor
Optimize retry scheduling
Minimize API calls through intelligent batching

Monitoring and Alerting

Payment Success Monitoring

Track payment success rates
Alert on declining success rates
Monitor payment method expiration
Forecast payment failures

System Performance Tracking

Average processing time per recurring gift
API response time monitoring
Error rate alerting
Throughput optimization

Best Practices

Recurring Gift Management

Clear Communication: Set donor expectations for payment timing
Payment Method Maintenance: Proactive payment method updates
Flexible Scheduling: Accommodate donor preferences
Regular Monitoring: Track payment success and failure rates
Stewardship Planning: Appropriate recognition and communication

Data Quality

Validation Rules: Comprehensive validation before processing
Payment Method Verification: Regular payment method validation
Schedule Optimization: Efficient payment scheduling
Error Handling: Robust error recovery procedures
Audit Trails: Complete history of all changes

Integration Management

Sync Frequency: Appropriate sync timing for operations
Error Monitoring: Proactive error detection and resolution
Performance Tracking: Monitor processing efficiency
Backup Procedures: Regular recurring gift data backups
Testing Protocols: Thorough testing of payment processing

Troubleshooting Guide

Common Processing Issues

Payment Failures

Check payment method validity and expiration
Verify bank account or card status
Review payment processor connectivity
Validate payment amount and currency

Schedule Problems

Review frequency and date calculations
Check for business day adjustments
Validate timezone settings
Confirm holiday and weekend handling

Status Inconsistencies

Compare status between systems
Check status transition rules
Verify manual status changes
Review automated status updates

Data Quality Issues

Missing Information

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

Payment History Discrepancies

Compare payment records between systems
Check for duplicate payment recording
Verify payment status accuracy
Review refund and reversal handling

Performance Problems

Slow Processing

Optimize batch sizes for payment volume
Review payment processor response times
Check network connectivity and latency
Monitor system resource utilization

High Failure Rates

Analyze payment failure patterns
Review payment method management
Check processor status and issues
Validate payment scheduling logic

Support Resources

Documentation References

Support Contacts

WeGive Support: [email protected]
Blackbaud Developer Support: Developer Community
Payment Processing Support: Available for payment method and processing issues

Overview

Data Mapping

​Recurring Gift Data Mapping

​Object Overview

​WeGive Recurring Donation Object

​Blackbaud Recurring Gift Object

​Core Recurring Gift Mapping

​Basic Recurring Gift Information

​Donor and Constituency

​Payment Schedule Configuration

​Frequency Mapping

​Status Mapping

​Fund Designation and Campaign Attribution

​Single Fund Designation

​Multiple Fund Designations

​Campaign and Appeal Attribution

​Payment Method and Processing

​Payment Method Information

​Payment Method Mapping

​Processing Configuration

​Pledge Integration

​Pledge Relationship

​Commitment Tracking

​Gift History and Tracking

​Payment History

​Payment Statistics

​Donor Communication and Stewardship

​Communication Preferences

​Recognition and Acknowledgment

​Modification and Lifecycle Management

​Recurring Gift Modifications

​Cancellation and Completion

​Custom Fields and Attributes

​Extended Recurring Gift Information

​Sustainer Program Integration

​Data Transformation Rules

​Amount and Financial Processing

​Schedule and Frequency Processing

​Status and Lifecycle Management

​Sync Behavior

​Create Operations

​Update Operations

​Cancellation and Completion Operations

​API Examples

​Create Recurring Gift Record

​Update Recurring Gift Status

​Recurring Gift with Multiple Designations

​Error Handling and Validation

​Required Field Validation

​Common Error Scenarios

​Retry and Recovery Logic

​Performance Optimization

​Batch Processing

​Monitoring and Alerting

​Best Practices

​Recurring Gift Management

​Data Quality

​Integration Management

​Troubleshooting Guide

​Common Processing Issues

​Data Quality Issues

​Performance Problems

​Support Resources

​Documentation References

​Support Contacts