> ## Documentation Index
> Fetch the complete documentation index at: https://wegive.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Neon Recurring Donation Mapping

> Detailed mapping between Neon CRM recurring donation objects and WeGive scheduled donation records

# 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

| WeGive Field   | Neon Field     | Data Type   | Direction     | Required | Transformation          |
| -------------- | -------------- | ----------- | ------------- | -------- | ----------------------- |
| `id`           | Correlation ID | UUID/String | -             | No       | Stored for tracking     |
| `chargeAmount` | `amount`       | Decimal     | Bidirectional | Yes      | Cents to dollars (÷100) |
| `currency`     | Currency       | String      | Export        | No       | Default USD             |

#### Donor Association

| WeGive Field     | Neon Field  | Data Type | Direction     | Required | Transformation    |
| ---------------- | ----------- | --------- | ------------- | -------- | ----------------- |
| `source` (donor) | `accountId` | Integer   | Bidirectional | Yes      | Donor correlation |

#### Schedule Information

| WeGive Field | Neon Field        | Data Type | Direction     | Required | Transformation        |
| ------------ | ----------------- | --------- | ------------- | -------- | --------------------- |
| `start_date` | `nextDate`        | Date      | Bidirectional | Yes      | Date formatting       |
| `iteration`  | `recurringPeriod` | Integer   | Bidirectional | Yes      | Period count          |
| `frequency`  | Derived           | String    | Export        | No       | Frequency calculation |

#### Recurring Settings

| WeGive Field     | Neon Field            | Data Type | Direction     | Required | Transformation  |
| ---------------- | --------------------- | --------- | ------------- | -------- | --------------- |
| `recurring_type` | `recurringPeriodType` | String    | Export        | No       | Default "LIFE"  |
| `end_date`       | `endDate`             | Date      | Bidirectional | No       | Date formatting |

#### Campaign Association

| WeGive Field | Neon Field    | Data Type | Direction     | Required | Transformation     |
| ------------ | ------------- | --------- | ------------- | -------- | ------------------ |
| `campaign`   | `campaign.id` | Integer   | Bidirectional | No       | Campaign reference |

#### Integration Fields

| WeGive Field | Neon Field | Data Type | Direction   | Required | Transformation               |
| ------------ | ---------- | --------- | ----------- | -------- | ---------------------------- |
| `neon_id`    | `id`       | Integer   | Correlation | No       | Recurring donation reference |

## Frequency and Period Mapping

### Recurring Period Types

Neon CRM supports different recurring period types:

| Neon Period Type | Description              | WeGive Equivalent                   |
| ---------------- | ------------------------ | ----------------------------------- |
| `LIFE`           | Ongoing/indefinite       | Default for all recurring donations |
| `FIXED`          | Fixed number of payments | Limited support                     |
| `UNTIL_DATE`     | Until specific date      | Mapped to `end_date`                |

### Frequency Calculation

WeGive iteration intervals map to Neon recurring periods:

| WeGive Iteration | Neon Period | Description                 |
| ---------------- | ----------- | --------------------------- |
| `30`             | 1           | Monthly (every 30 days)     |
| `90`             | 3           | Quarterly (every 90 days)   |
| `365`            | 12          | Annually (every 365 days)   |
| Custom           | Calculated  | Custom intervals calculated |

### Period Calculation Logic

```javascript theme={null}
// 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```javascript theme={null}
// 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

```json theme={null}
{
  "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

```http theme={null}
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

```http theme={null}
PUT /v2/recurring/rec123
{
  "amount": 75.00,
  "nextDate": "2024-03-15"
}
```

### Getting Recurring Donations

```http theme={null}
GET /v2/recurring?accountId=67890
```

Response:

```json theme={null}
[
  {
    "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.