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

# Donation Mapping

> Detailed mapping between WeGive transactions and Planning Center donation records with batch processing

# Donation Mapping

This document provides comprehensive mapping details between WeGive transaction objects and Planning Center donation records, including batch processing, fund designations, and payment source management.

## Overview

Planning Center's Giving module uses the **Donation** object to represent individual gifts, organized into **Batches** for accounting purposes. Each donation can have multiple **Designations** for fund allocation and links to **PaymentSource** objects for payment tracking. WeGive maps these to the **Transaction** object with appropriate batch organization.

## Core Donation Mapping

### Primary Fields

| WeGive Field         | Planning Center Field | Type      | Required | Transformation                        |
| -------------------- | --------------------- | --------- | -------- | ------------------------------------- |
| `id`                 | Correlation ID        | String    | No       | Stored in WeGive `planning_center_id` |
| `amount`             | `amount_cents`        | Integer   | Yes      | Direct cents mapping                  |
| `created_at`         | `created_at`          | DateTime  | Yes      | ISO 8601 format                       |
| `owner` (donor\_id)  | `person`              | Reference | Yes      | Person object reference               |
| `status`             | Status indicator      | String    | No       | Transaction status mapping            |
| `planning_center_id` | `id`                  | String    | No       | Donation ID correlation               |

### Extended Fields

| WeGive Field | Planning Center Field | Transformation       | Notes                 |
| ------------ | --------------------- | -------------------- | --------------------- |
| `currency`   | `currency`            | Direct mapping       | Defaults to USD       |
| `reference`  | Internal reference    | Transaction tracking | WeGive transaction ID |
| `memo`       | `memo`                | Direct mapping       | Internal notes        |
| `fee_amount` | `fee_cents`           | Direct cents mapping | Processing fees       |

## Batch Processing Integration

### Daily Batch Organization

**Batch Creation Logic:**

* Donations grouped by transaction date (not processing date)
* Daily batch format: "WeGive Import - \[YYYY-MM-DD]"
* All WeGive transactions for a specific day included in single batch
* Automatic batch creation during push operations

**Batch Object Structure:**

| WeGive Data       | Planning Center Field  | Transformation       | Notes                        |
| ----------------- | ---------------------- | -------------------- | ---------------------------- |
| Transaction date  | Batch.description      | Date-based naming    | "WeGive Import - 2024-01-15" |
| Daily total       | Batch.total\_cents     | Sum of all donations | Batch total validation       |
| Transaction count | Batch.donations\_count | Count of donations   | Batch completeness check     |
| Processing time   | Batch.committed\_at    | Batch finalization   | Automatic commitment         |

### Batch Processing Workflow

**Batch Creation Process:**

1. **Group Transactions**: Organize WeGive transactions by date
2. **Create Batch**: Create Planning Center batch with descriptive name
3. **Add Donations**: Create donation records within batch
4. **Validate Totals**: Verify batch totals match transaction sums
5. **Commit Batch**: Finalize batch for accounting purposes
6. **Error Handling**: Rollback entire batch if any donation fails

**Batch Status Management:**

* **Uncommitted**: Batch created but not finalized
* **Committed**: Batch finalized and ready for accounting
* **Failed**: Batch processing failed, requires attention
* **Rolled Back**: Batch reversed due to errors

## Fund Designation Mapping

### Single Fund Designation

**Simple Fund Assignment:**

* WeGive transaction with single fund creates one Designation
* Designation amount equals full transaction amount
* Fund reference links to Planning Center fund object
* Default fund used when no specific designation provided

**Designation Object Structure:**

| WeGive Field   | Planning Center Field     | Transformation        | Notes                   |
| -------------- | ------------------------- | --------------------- | ----------------------- |
| `amount`       | Designation.amount\_cents | Direct cents mapping  | Full transaction amount |
| `fund_id`      | Designation.fund          | Fund object reference | Planning Center fund    |
| Transaction ID | Designation.donation      | Donation reference    | Parent donation         |

### Multiple Fund Designations

**Split Fund Handling:**

* WeGive fund allocations create multiple Designation objects
* Each allocation creates separate designation with specific amount
* Designation amounts must sum to total donation amount
* All designations linked to same donation record

**Split Designation Example:**

* WeGive transaction: $100 split between two funds ($60 + \$40)
* Creates one Donation object for \$100
* Creates two Designation objects: $60 to Fund A, $40 to Fund B
* Validation ensures $60 + $40 = \$100 total

### Default Fund Assignment

**Fund Assignment Priority:**

1. **Specific Fund**: Use designated fund from WeGive transaction
2. **Default Fund**: Use configured default fund when no designation
3. **General Fund**: Fall back to organization's general fund
4. **Error Handling**: Transaction fails if no valid fund available

**Default Fund Configuration:**

* Default fund ID stored in integration settings
* Must be active and valid Planning Center fund
* Used for transactions without specific fund designation
* Prevents donation processing failures

## Payment Source Management

### WeGive Payment Source

**Unified Payment Source Strategy:**

* All WeGive transactions use single "WeGive" payment source
* Payment source created automatically during setup
* Original payment method preserved in transaction metadata
* Simplifies Planning Center payment source management

**Payment Source Object:**

| WeGive Data            | Planning Center Field     | Transformation | Notes                            |
| ---------------------- | ------------------------- | -------------- | -------------------------------- |
| "WeGive"               | PaymentSource.name        | Fixed value    | All transactions use this source |
| Payment method details | PaymentSource.description | Method summary | Original payment method info     |
| Electronic             | PaymentSource.type        | Fixed type     | Categorization for reporting     |

### Payment Method Preservation

**Original Payment Method Tracking:**

* WeGive payment method stored in donation metadata
* Credit card, ACH, check details preserved
* Payment method accessible for detailed reporting
* Transaction-level payment information maintained

**Payment Method Types:**

| WeGive Source Type | Preserved Information    | Planning Center Usage   |
| ------------------ | ------------------------ | ----------------------- |
| `card`             | Card type, last 4 digits | "WeGive" payment source |
| `bank`             | Bank name, account type  | "WeGive" payment source |
| `check`            | Check number, date       | "WeGive" payment source |
| `cash`             | Cash designation         | "WeGive" payment source |
| `other`            | Method description       | "WeGive" payment source |

## Data Transformation

### Donation Creation Processing

**WeGive to Planning Center Donation:**

1. **Validate Transaction**: Ensure amount, date, and donor are valid
2. **Resolve Person**: Link to existing Planning Center person or create new
3. **Determine Batch**: Assign to daily batch or create new batch
4. **Create Donation**: Create donation record with transaction details
5. **Create Designations**: Create fund allocation designations
6. **Link Payment Source**: Assign to "WeGive" payment source
7. **Store Correlation**: Save Planning Center donation ID

**Amount and Currency Processing:**

* WeGive amounts stored in cents, mapped directly to Planning Center
* Currency code preserved (defaults to USD)
* Fee amounts mapped to separate fee fields
* Amount validation ensures positive values

### Date and Time Handling

**Date Processing:**

* WeGive transaction created\_at mapped to donation created\_at
* Date used for batch organization (by date, not datetime)
* Timezone considerations for accurate date grouping
* Historical transaction dating preserved

## Sync Operations

### Push Operation (WeGive → Planning Center)

#### Create New Donation

**Process:**

1. **Batch Determination**: Find or create daily batch for transaction date
2. **Person Validation**: Ensure donor exists in Planning Center
3. **Donation Creation**: Create donation with amount, date, and person
4. **Designation Creation**: Create fund allocation designations
5. **Payment Source Assignment**: Link to "WeGive" payment source
6. **Batch Update**: Update batch totals and counts
7. **Correlation Storage**: Store donation ID for future updates

#### Batch Commitment

**Process:**

1. **Batch Validation**: Verify all donations in batch are valid
2. **Total Verification**: Confirm batch total matches sum of donations
3. **Designation Validation**: Ensure all designations are properly assigned
4. **Batch Commitment**: Finalize batch for accounting
5. **Error Handling**: Rollback entire batch if any issues detected

### Pull Operation (Planning Center → WeGive)

#### Import Donation

**Process:**

1. **Donation Retrieval**: Get donation with related data (person, designations)
2. **Person Resolution**: Map Planning Center person to WeGive donor
3. **Amount Processing**: Convert amount and handle currency
4. **Fund Mapping**: Map designations to WeGive funds
5. **Transaction Creation**: Create or update WeGive transaction
6. **Correlation Storage**: Store donation ID for bidirectional sync

#### Batch Information Processing

**Batch Data Import:**

* Batch information preserved in transaction metadata
* Batch date and description accessible for reporting
* Batch commitment status tracked
* Historical batch organization maintained

## Recurring Donation Integration

### Recurring Gift Relationship

**Recurring Donation Tracking:**

* Individual donations linked to recurring gift schedules
* Sequence number tracking within recurring series
* Schedule modification impact on individual donations
* Automated recurring donation processing

**Recurring Gift Coordination:**

* WeGive scheduled donations mapped to Planning Center recurring gifts
* Individual transactions created from recurring gift schedules
* Payment method and fund consistency across recurring series
* Schedule changes reflected in individual donations

## Validation and Error Handling

### Donation Validation

**Required Field Validation:**

* Amount must be positive value
* Donation date is required and reasonable
* Person reference must exist and be valid
* At least one fund designation required

**Business Rule Validation:**

* Donation amount matches sum of designations
* Fund references are active and valid
* Person is not marked as deceased
* Batch totals are accurate

### Error Handling

**Common Donation Errors:**

* Invalid person reference (donor doesn't exist)
* Missing or inactive fund designation
* Amount validation failures (negative, zero)
* Batch processing errors

**Error Recovery:**

* **Person Creation**: Create Planning Center person for missing donors
* **Default Fund Assignment**: Use default fund for invalid designations
* **Batch Rollback**: Reverse entire batch for critical errors
* **Manual Review**: Queue problematic donations for review

### Batch Error Handling

**Batch-Level Errors:**

* Single donation failure doesn't fail entire batch
* Critical errors trigger full batch rollback
* Partial batch processing with error isolation
* Comprehensive error logging for troubleshooting

## Performance Optimization

### Batch Processing Efficiency

**Daily Batch Strategy:**

* Optimize API usage through batch organization
* Reduce individual API calls for donations
* Efficient batch commitment process
* Background processing for large batches

**Processing Optimization:**

* Person lookup optimization before donation creation
* Fund validation caching
* Batch total calculation efficiency
* Payment source reuse across donations

### API Usage Optimization

**Request Minimization:**

* Batch creation with multiple donations
* Efficient designation creation
* Combined person and donation validation
* Optimized fund and payment source references

## Integration with Accounting

### Financial Reporting Integration

**Batch-Based Reporting:**

* Daily batches provide accounting structure
* Batch totals enable financial reconciliation
* Fund designation reporting
* Payment source categorization

**Audit Trail Maintenance:**

* Complete donation history preservation
* Batch processing logs
* Fund designation tracking
* Payment source attribution

### Reconciliation Support

**Data Reconciliation:**

* Batch total validation
* Fund allocation verification
* Payment source consistency
* Person relationship integrity

This comprehensive donation mapping ensures accurate financial transaction synchronization between WeGive and Planning Center while maintaining proper accounting structure and audit trails for effective church financial management.