​

Recurring Donation Object Mapping

This document details the comprehensive mapping between Neon CRM recurring donation objects and WeGive scheduled donation records, including payment scheduling, donor management, and synchronization behavior.

​

Object Overview

​

Neon Recurring Donation Object

Represents scheduled recurring gifts in Neon CRM including frequency, amount, and payment scheduling.

​

WeGive Scheduled Donation Object

Represents recurring donation schedules in WeGive including payment processing, donor attribution, and automation.

​

Core Recurring Donation Mapping

​

WeGive Scheduled Donation to Neon Recurring Donation

​

Basic Information

​

Donor Association

​

Schedule Information

​

Recurring Settings

​

Campaign Association

​

Integration Fields

​

Frequency and Period Mapping

​

Recurring Period Types

Neon CRM supports different recurring period types:

​

Frequency Calculation

WeGive iteration intervals map to Neon recurring periods:

​

Period Calculation Logic

// Convert WeGive iteration (days) to Neon period (months)
function calculateNeonPeriod(wegiveIteration) {
  if (wegiveIteration <= 30) return 1;    // Monthly
  if (wegiveIteration <= 90) return 3;    // Quarterly  
  if (wegiveIteration <= 365) return 12;  // Annually
  return Math.round(wegiveIteration / 30); // Custom
}

​

Payment Integration

​

Payment Method Association

Recurring donations inherit payment methods from the associated donor:

​

Credit Card Recurring

• Payment Method: Uses donor’s default payment method
• Processing: Automatic processing on schedule
• Security: Payment method securely stored and referenced
• Updates: Payment method updates affect future charges

​

Bank Transfer Recurring

• ACH Processing: Automated ACH transfers on schedule
• Bank Account: Uses donor’s verified bank account
• Processing Time: Accounts for ACH processing delays
• Failure Handling: Automatic retry logic for failed payments

​

Payment Processing Schedule

• Next Payment: nextDate field tracks next scheduled payment
• Frequency: recurringPeriod determines payment frequency
• End Date: Optional end date for limited-term recurring gifts
• Status: Active/inactive status controls processing

​

Complete Recurring Donation Structure

​

Full Neon Recurring Donation Object

{
  "id": "rec123",
  "accountId": "67890",
  "amount": 50.00,
  "nextDate": "2024-02-15",
  "recurringPeriod": 1,
  "recurringPeriodType": "LIFE",
  "campaign": {
    "id": "789",
    "name": "Monthly Giving Program",
    "status": "ACTIVE"
  },
  "endDate": null,
  "status": "ACTIVE"
}

​

WeGive Scheduled Donation Structure

{
  "id": "sched456",
  "source_id": "donor123",
  "chargeAmount": 5000,
  "start_date": "2024-02-15",
  "iteration": 30,
  "frequency": "monthly",
  "campaign_id": "camp789",
  "neon_id": "rec123",
  "status": "active"
}

​

Data Transformations

​

Amount Conversion

• WeGive Storage: Amounts stored in cents (integer)
• Neon Format: Amounts in dollars (decimal)
• Conversion: WeGive amount ÷ 100 = Neon amount
• Example: WeGive 5000 cents = Neon $50.00

​

Date Formatting

• WeGive Format: ISO 8601 date
• Neon Format: Date only (YYYY-MM-DD)
• Timezone: Converted to organization’s timezone
• Next Payment: Calculated based on frequency and start date

​

Frequency Mapping

// WeGive to Neon frequency mapping
function mapFrequencyToNeon(wegiveIteration) {
  switch(wegiveIteration) {
    case 7: return { period: 1, type: "WEEKLY" };     // Weekly
    case 30: return { period: 1, type: "MONTHLY" };   // Monthly
    case 90: return { period: 3, type: "QUARTERLY" }; // Quarterly
    case 365: return { period: 12, type: "ANNUALLY" }; // Annually
    default: return { period: Math.round(wegiveIteration / 30), type: "CUSTOM" };
  }
}

​

Synchronization Behavior

​

Recurring Donation Creation

1. Donor Verification: Ensures donor account exists in Neon CRM
2. Payment Method: Verifies valid payment method for recurring processing
3. Campaign Sync: Syncs associated campaign if specified
4. Schedule Setup: Establishes recurring payment schedule

​

Recurring Donation Updates

1. Existing Check: Uses neon_id to identify existing recurring donations
2. Schedule Changes: Updates payment frequency and amounts
3. Status Changes: Handles activation/deactivation of recurring gifts
4. Payment Method: Updates payment method if changed

​

Import from Neon CRM

1. Active Filter: Only imports active recurring donations
2. Donor Matching: Matches Neon accounts to WeGive donors
3. Schedule Creation: Creates WeGive scheduled donations
4. Payment Setup: Establishes payment processing schedules

​

Campaign Integration

​

Campaign Association

When recurring donations are associated with campaigns:

​

Campaign Reference

{
  "campaign": {
    "id": "789",
    "name": "Monthly Giving Program",
    "status": "ACTIVE"
  }
}

​

Campaign Validation

• Campaign must exist in both systems
• Campaign must be in ACTIVE status
• Campaign correlation established before recurring donation creation

​

Statistics Impact

• Recurring donations contribute to campaign statistics
• Monthly totals calculated automatically
• Projected revenue based on recurring schedules
• Donor retention metrics improved with recurring gifts

​

Error Handling

​

Validation Errors

• Missing Donor: Donor account must exist before recurring donation
• Invalid Amount: Amount must be positive and within limits
• Invalid Schedule: Start date must be in future, frequency must be valid
• Payment Method: Valid payment method required for processing

​

Common Issues

• Payment Failures: Automatic retry logic for failed payments
• Account Changes: Handling donor account updates
• Campaign Deactivation: Managing recurring donations when campaigns end
• Payment Method Expiration: Notifications for expired payment methods

​

Resolution Strategies

• Donor Creation: Automatic donor account creation when missing
• Payment Updates: Tools for updating payment methods
• Schedule Adjustments: Administrative tools for schedule modifications
• Manual Processing: Manual payment processing for failed automation

​

Performance Considerations

​

Processing Optimization

• Batch Processing: Efficient processing of multiple recurring donations
• Schedule Optimization: Optimized calculation of payment schedules
• Payment Batching: Batch payment processing for efficiency
• Error Recovery: Graceful handling of processing failures

​

Memory Management

• Large Datasets: Efficient processing of large recurring donation sets
• Payment History: Optimized storage and retrieval of payment history
• Schedule Calculations: Efficient recurring schedule calculations
• Correlation Tracking: Optimized correlation ID management

​

API Examples

​

Creating Recurring Donation

POST /v2/recurring
{
  "accountId": "67890",
  "amount": 100.00,
  "nextDate": "2024-03-01",
  "recurringPeriod": 1,
  "recurringPeriodType": "LIFE",
  "campaign": {
    "id": "789",
    "name": "Monthly Giving Program",
    "status": "ACTIVE"
  }
}

​

Updating Recurring Donation

PUT /v2/recurring/rec123
{
  "amount": 75.00,
  "nextDate": "2024-03-15"
}

​

Getting Recurring Donations

GET /v2/recurring?accountId=67890

Response:

[
  {
    "id": "rec123",
    "accountId": "67890",
    "amount": 75.00,
    "nextDate": "2024-03-15",
    "recurringPeriod": 1,
    "recurringPeriodType": "LIFE",
    "status": "ACTIVE"
  }
]

​

Best Practices

​

Recurring Donation Management

• Clear Communication: Communicate recurring schedules clearly to donors
• Payment Validation: Validate payment methods before setup
• Schedule Flexibility: Provide easy schedule modification options
• Failure Handling: Implement robust failure handling and notification

​

Integration Management

• Regular Monitoring: Monitor recurring donation processing and errors
• Payment Method Updates: Proactively manage payment method updates
• Campaign Coordination: Coordinate recurring donations with campaign strategies
• Donor Communication: Keep donors informed about recurring gift status

​

Data Quality

• Amount Validation: Ensure realistic recurring amounts
• Schedule Validation: Validate recurring schedules for feasibility
• Donor Verification: Verify donor authorization for recurring gifts
• Regular Cleanup: Review and clean up inactive recurring donations

​

Recurring Donation Analytics

​

Performance Metrics

• Recurring Revenue: Track monthly recurring revenue
• Donor Retention: Monitor recurring donor retention rates
• Payment Success: Track payment processing success rates
• Campaign Performance: Analyze recurring donations by campaign

​

Reporting Features

• Revenue Projections: Project future revenue from recurring donations
• Donor Lifecycle: Track donor journey with recurring gifts
• Payment Analytics: Analyze payment method performance
• Campaign Attribution: Attribute recurring revenue to campaigns

​

Advanced Features

​

Automated Processing

• Payment Scheduling: Automated payment processing on schedule
• Failure Recovery: Automatic retry for failed payments
• Donor Notifications: Automated donor communication
• Reporting: Automated recurring donation reports

​

Customization Options

• Flexible Scheduling: Support for custom recurring schedules
• Campaign Integration: Flexible campaign association options
• Payment Options: Multiple payment method support
• Donor Preferences: Configurable donor communication preferences

This comprehensive recurring donation mapping ensures effective management of ongoing donor relationships and automated revenue generation between WeGive and Neon CRM.