> ## 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 Donation Mapping

> Detailed field mapping for recurring donations and pledges between WeGive and DonorPerfect systems.

# Recurring Donation Data Mapping

This document details how recurring donations and pledges are mapped between WeGive and DonorPerfect, including pledge creation, payment tracking, and schedule management.

## DonorPerfect Table Reference

**Primary Table**: `dppledge` (Pledge Records)\
**WeGive Model**: `ScheduledDonation`\
**Sync Direction**: WeGive → DonorPerfect (Push Only)

## Recurring Donation Overview

### Integration Approach

<AccordionGroup>
  <Accordion title="Pledge vs. Scheduled Donation">
    **WeGive Side**:

    * `ScheduledDonation`: Recurring giving setup
    * Individual `Transaction` records for each payment
    * Flexible frequency options (monthly, quarterly, annual)

    **DonorPerfect Side**:

    * `dppledge`: Pledge commitment record
    * `dpgift`: Individual payment records linked to pledge
    * Simplified frequency mapping (defaults to monthly)
  </Accordion>

  <Accordion title="Data Flow Pattern">
    **Process Overview**:

    1. WeGive scheduled donation creates DonorPerfect pledge
    2. Individual payments create linked gift records
    3. Pledge status updates based on payment activity
    4. Schedule modifications sync to pledge record
  </Accordion>
</AccordionGroup>

## Core Pledge Fields

### Primary Identifiers

<AccordionGroup>
  <Accordion title="Pledge Identification">
    | WeGive Field   | DonorPerfect Field | Type    | Notes                                 |
    | -------------- | ------------------ | ------- | ------------------------------------- |
    | `dp_id`        | `@pledge_id`       | Integer | Auto-generated DonorPerfect pledge ID |
    | `source.dp_id` | `@donor_id`        | Integer | Links to donor record                 |
    | N/A            | `@user_id`         | String  | Always set to 'WeGive'                |
  </Accordion>

  <Accordion title="Relationship Linking">
    **Connection Strategy**:

    * Each WeGive scheduled donation creates one DonorPerfect pledge
    * Individual payments reference the pledge ID
    * Donor must exist in DonorPerfect before creating pledge
    * Pledge ID stored back in WeGive for payment linking
  </Accordion>
</AccordionGroup>

## Financial Information

### Amount and Payment Details

<Warning>
  **Amount Calculation**: Includes processing fees in pledge amount, matching the total charged to donor.
</Warning>

| WeGive Field    | DonorPerfect Field | Calculation             | Notes                          |
| --------------- | ------------------ | ----------------------- | ------------------------------ |
| `amount + fees` | `@bill`            | `(amount + fees) / 100` | Total pledge amount in dollars |
| `created_at`    | `@gift_date`       | MM/DD/YYYY              | Pledge creation date           |
| `created_at`    | `@start_date`      | MM/DD/YYYY              | First payment date             |

#### Amount Calculation Examples

<AccordionGroup>
  <Accordion title="Standard Recurring Gift">
    **WeGive Scheduled Donation**:

    * Amount: \$50.00 (5000 cents)
    * Processing Fee: \$1.75 (175 cents)

    **DonorPerfect Pledge**:

    * Bill Amount: \$51.75 ((5000 + 175) / 100)
    * Reflects total amount charged to donor
  </Accordion>

  <Accordion title="Fee-Covered Recurring Gift">
    **WeGive Scheduled Donation**:

    * Amount: \$50.00 (5000 cents)
    * Processing Fee: \$0.00 (donor covers separately)

    **DonorPerfect Pledge**:

    * Bill Amount: \$50.00 ((5000 + 0) / 100)
  </Accordion>
</AccordionGroup>

### Schedule and Frequency

<AccordionGroup>
  <Accordion title="Frequency Mapping">
    | WeGive Frequency | DonorPerfect Field | Value | Notes                |
    | ---------------- | ------------------ | ----- | -------------------- |
    | Any frequency    | `@frequency`       | 'M'   | Hardcoded to Monthly |

    **Limitation**: DonorPerfect integration currently maps all recurring gifts as monthly frequency, regardless of actual WeGive schedule.
  </Accordion>

  <Accordion title="Schedule Details">
    **Date Handling**:

    * Start Date: Set to scheduled donation creation date
    * Gift Date: Also set to creation date
    * Actual payment dates handled by individual gift records
    * Schedule modifications require pledge updates
  </Accordion>
</AccordionGroup>

## Gift Narrative and Description

### Automatic Description Generation

<AccordionGroup>
  <Accordion title="Standard Pledge Narrative">
    | WeGive Field | DonorPerfect Field | Value                        | Notes                |
    | ------------ | ------------------ | ---------------------------- | -------------------- |
    | Generated    | `@gift_narrative`  | "Online gift through WeGive" | Standard description |

    **Narrative Examples**:

    * Regular pledge: "Online gift through WeGive"
    * Anonymous pledge: "Online gift through WeGive (Anonymous)"
  </Accordion>

  <Accordion title="Description Consistency">
    **Matching Records**:

    * Pledge narrative matches individual payment narratives
    * Consistent branding across all related records
    * Anonymous handling applies to both pledge and payments
  </Accordion>
</AccordionGroup>

## Payment Processing Integration

### Individual Payment Tracking

<AccordionGroup>
  <Accordion title="Payment-to-Pledge Linking">
    **Transaction Processing**:

    * Each scheduled payment creates a `dpgift` record
    * Gift record includes `@pledge_payment = 'Y'`
    * Links back to original pledge via donor ID and dates
    * Payment status tracked in both systems
  </Accordion>

  <Accordion title="Payment Sequence">
    **Processing Flow**:

    1. Pledge created in DonorPerfect from scheduled donation
    2. First payment processes and creates linked gift record
    3. Subsequent payments automatically link to pledge
    4. Failed payments update pledge status accordingly
  </Accordion>
</AccordionGroup>

### Status Management

<AccordionGroup>
  <Accordion title="Pledge Status Tracking">
    **Status Indicators**:

    * Active pledges with regular payments
    * Paused pledges with temporary holds
    * Cancelled pledges with stopped payments
    * Completed pledges with fulfilled commitments
  </Accordion>

  <Accordion title="Automatic Updates">
    **Status Synchronization**:

    * Payment success/failure updates pledge status
    * Schedule modifications sync to DonorPerfect
    * Cancellations properly close pledge records
    * Reactivations update pledge accordingly
  </Accordion>
</AccordionGroup>

## Data Flow Process

### Pledge Creation Workflow

<Steps>
  <Step title="Scheduled Donation Setup">
    Donor sets up recurring gift in WeGive
  </Step>

  <Step title="Donor Validation">
    Verify donor exists in DonorPerfect (create if needed)
  </Step>

  <Step title="Pledge Record Creation">
    Create pledge record in DonorPerfect dppledge table
  </Step>

  <Step title="Payment Processing">
    First payment creates linked dpgift record
  </Step>

  <Step title="Ongoing Sync">
    Subsequent payments automatically link to pledge
  </Step>
</Steps>

### Schedule Modification Handling

<AccordionGroup>
  <Accordion title="Amount Changes">
    **Process**:

    * Update pledge amount in DonorPerfect
    * Future payments reflect new amount
    * Historical payments remain unchanged
    * Status updated to reflect modification
  </Accordion>

  <Accordion title="Frequency Changes">
    **Limitation**:

    * DonorPerfect frequency remains 'M' (Monthly)
    * Actual schedule managed by WeGive system
    * Payment timing controlled by WeGive processing
    * No frequency sync to DonorPerfect
  </Accordion>

  <Accordion title="Cancellation Handling">
    **Process**:

    * Pledge status updated to cancelled
    * No new payment records created
    * Historical data preserved
    * Donor communication handled separately
  </Accordion>
</AccordionGroup>

## API Operations

### DonorPerfect Pledge Creation

<AccordionGroup>
  <Accordion title="dp_savepledge Action">
    **Required Parameters**:

    ```
    @pledge_id (empty for new pledges)
    @donor_id (required)
    @gift_date (MM/DD/YYYY format)
    @start_date (MM/DD/YYYY format)
    @bill (decimal dollars)
    @frequency = 'M'
    @user_id = 'WeGive'
    ```
  </Accordion>

  <Accordion title="Optional Parameters">
    **Additional Fields**:

    ```
    @gift_narrative (description)
    @gl_code (fund designation)
    @pledge_status (active/cancelled)
    ```
  </Accordion>
</AccordionGroup>

### Query Operations

<AccordionGroup>
  <Accordion title="Pledge Lookup">
    **SQL Query Example**:

    ```sql theme={null}
    SELECT pledge_id, donor_id, gift_date, bill, frequency
    FROM dppledge 
    WHERE user_id = 'WeGive'
      AND start_date >= 'MM/DD/YYYY'
    ORDER BY pledge_id DESC
    ```
  </Accordion>
</AccordionGroup>

## Error Handling

### Common Pledge Sync Issues

<Warning>
  **Pledge Dependencies**: Pledges require valid donor records and fund GL codes before creation.
</Warning>

| Error Type           | Cause                               | Resolution                      |
| -------------------- | ----------------------------------- | ------------------------------- |
| **Invalid Donor**    | Donor doesn't exist in DonorPerfect | Auto-create donor, retry pledge |
| **Invalid Amount**   | Negative or zero pledge amount      | Skip creation, log error        |
| **Date Format**      | Invalid start/gift date format      | Correct format, retry           |
| **Duplicate Pledge** | Pledge already exists for donor     | Update existing pledge          |
| **API Timeout**      | DonorPerfect API unavailable        | Retry with backoff delay        |

### Payment Processing Errors

<AccordionGroup>
  <Accordion title="Failed Payment Handling">
    **Error Scenarios**:

    * Payment processing failures
    * Expired payment methods
    * Insufficient funds
    * Bank declines

    **Resolution Process**:

    * Retry payment according to schedule
    * Update pledge status if multiple failures
    * Notify donor of payment issues
    * Maintain pledge record for future attempts
  </Accordion>
</AccordionGroup>

## Sync Configuration

### Recurring Donation Settings

<AccordionGroup>
  <Accordion title="Sync Triggers">
    **Automatic Sync Events**:

    * New scheduled donation created
    * Recurring payment processed
    * Schedule modifications (amount, frequency)
    * Donation cancellation or pause
    * Donor profile updates
  </Accordion>

  <Accordion title="Sync Timing">
    **Processing Schedule**:

    * **Real-time**: New pledges sync immediately
    * **Payment Processing**: Individual payments sync as processed
    * **Status Updates**: Schedule changes sync within minutes
    * **Error Recovery**: Failed syncs retry automatically
  </Accordion>
</AccordionGroup>

### Performance Considerations

<CardGroup cols={2}>
  <Card title="Pledge Management" icon="calendar">
    * Efficient pledge creation and updates
    * Batch processing for multiple changes
    * Automatic status synchronization
    * Optimized query performance
  </Card>

  <Card title="Payment Integration" icon="credit-card">
    * Real-time payment-to-pledge linking
    * Automatic gift record creation
    * Status updates for payment outcomes
    * Comprehensive error handling
  </Card>
</CardGroup>

## Data Quality and Validation

### Pre-Sync Validation

<AccordionGroup>
  <Accordion title="Pledge Requirements">
    **Validation Rules**:

    * Donor must exist in DonorPerfect
    * Pledge amount must be positive
    * Start date must be valid
    * Frequency must be supported
    * Fund designation must be valid
  </Accordion>

  <Accordion title="Payment Validation">
    **Payment Processing Checks**:

    * Valid payment method on file
    * Sufficient account balance
    * Active pledge record exists
    * Proper payment amount calculation
  </Accordion>
</AccordionGroup>

### Monitoring and Reporting

<AccordionGroup>
  <Accordion title="Pledge Performance">
    **Dashboard Metrics**:

    * Active pledge count and total value
    * Payment success rates
    * Pledge completion rates
    * Average pledge duration
  </Accordion>

  <Accordion title="Financial Reconciliation">
    **Accuracy Verification**:

    * Pledge amount vs. payment totals
    * Fee inclusion verification
    * Payment frequency accuracy
    * Status consistency checks
  </Accordion>
</AccordionGroup>

## Limitations and Considerations

### Known Limitations

<Warning>
  **Important Limitations**:
</Warning>

<AccordionGroup>
  <Accordion title="Frequency Mapping">
    **Limitation**: All pledges mapped as monthly frequency in DonorPerfect

    **Impact**:

    * DonorPerfect reports may not reflect actual payment schedule
    * Actual timing controlled by WeGive system
    * Payment dates may not align with monthly expectation
  </Accordion>

  <Accordion title="Schedule Modifications">
    **Limitation**: Limited support for complex schedule changes

    **Impact**:

    * Frequency changes don't sync to DonorPerfect
    * Amount changes require pledge updates
    * Pause/resume functionality may not reflect perfectly
  </Accordion>
</AccordionGroup>

### Best Practices

<Steps>
  <Step title="Plan Pledge Structure">
    Design recurring giving programs with DonorPerfect limitations in mind
  </Step>

  <Step title="Monitor Payment Success">
    Regularly review payment processing and pledge status
  </Step>

  <Step title="Handle Modifications Carefully">
    Test schedule changes to ensure proper sync behavior
  </Step>

  <Step title="Maintain Data Quality">
    Keep donor and fund information accurate and up-to-date
  </Step>
</Steps>

## Troubleshooting

### Common Recurring Donation Issues

<AccordionGroup>
  <Accordion title="Pledges Not Creating">
    **Possible Causes**:

    * Recurring donation sync disabled
    * Donor missing from DonorPerfect
    * Invalid pledge amount
    * API authentication issues

    **Solutions**:

    * Enable recurring donation tracking
    * Verify donor sync status
    * Check amount calculation logic
    * Test API credentials
  </Accordion>

  <Accordion title="Payments Not Linking to Pledges">
    **Possible Causes**:

    * Pledge record missing
    * Donor ID mismatch
    * Date formatting issues

    **Solutions**:

    * Verify pledge creation success
    * Check donor ID consistency
    * Review date format requirements
  </Accordion>

  <Accordion title="Incorrect Pledge Amounts">
    **Possible Causes**:

    * Fee calculation errors
    * Amount conversion issues
    * Currency problems

    **Solutions**:

    * Review fee inclusion logic
    * Check amount calculation
    * Verify currency settings
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Transaction Mapping" href="/donorperfect/data-mapping/transaction">
    How individual payments link to pledges
  </Card>

  <Card title="Donor Mapping" href="/donorperfect/data-mapping/donor">
    Donor record requirements for pledges
  </Card>

  <Card title="Fund Management" href="/donorperfect/data-mapping/fund">
    GL code setup for recurring gifts
  </Card>

  <Card title="Configuration Guide" href="/donorperfect/configuration-options">
    Configure recurring donation sync settings
  </Card>
</CardGroup>

For additional help with recurring donation mapping, contact our support team at [support@wegive.com](mailto:support@wegive.com).