> ## 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.

# Recurring Gift Mapping

> Detailed field mapping between WeGive recurring donations and Blackbaud Raiser's Edge NXT recurring gifts

# 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**

1. Validate recurring gift data and requirements
2. Map payment method and schedule information
3. Link to existing constituent
4. Apply fund designations and campaign attribution
5. Create recurring gift record in Blackbaud
6. Store correlation ID for future updates
7. Initialize payment schedule

**New Blackbaud Recurring Gift → WeGive Recurring Donation**

1. Extract recurring gift and constituent information
2. Map to WeGive recurring donation format
3. Create or link to WeGive donor
4. Preserve fund and campaign attributions
5. 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**

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

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

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

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

### Data Quality

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

### Integration Management

1. **Sync Frequency**: Appropriate sync timing for operations
2. **Error Monitoring**: Proactive error detection and resolution
3. **Performance Tracking**: Monitor processing efficiency
4. **Backup Procedures**: Regular recurring gift data backups
5. **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

* [Blackbaud Recurring Gift API Documentation](https://developer.blackbaud.com/skyapi/docs/services/56b76470069a0509c8f1c5b3)
* [WeGive Recurring Donation API Documentation](https://api.wegive.com/docs/recurring-donations)
* [Gift Mapping Documentation](/blackbaud/data-mapping/gift)
* [Fund Mapping Documentation](/blackbaud/data-mapping/fund)

### Support Contacts

* **WeGive Support**: [support@wegive.com](mailto:support@wegive.com)
* **Blackbaud Developer Support**: [Developer Community](https://community.blackbaud.com/developer)
* **Payment Processing Support**: Available for payment method and processing issues