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

# Gift Mapping

> Detailed mapping between WeGive transactions and Virtuous gift records

# Gift Mapping

This document provides comprehensive mapping details between WeGive transaction objects and Virtuous gift records, including batch processing capabilities and integration with both V1 and V2 contact structures.

## Overview

Virtuous uses the **Gift** object to represent all financial interactions including donations, pledge payments, and recurring gifts. WeGive maps these to the **Transaction** object with appropriate categorization and metadata, with enhanced processing capabilities for both individual and batch operations.

## Core Gift Mapping

### Primary Fields

| WeGive Field        | Virtuous Field | Type     | Required | Transformation                     |
| ------------------- | -------------- | -------- | -------- | ---------------------------------- |
| `id`                | Correlation ID | String   | No       | Stored in WeGive `virtuous_id`     |
| `amount`            | `Amount`       | Decimal  | Yes      | Cents to dollars (÷100)            |
| `created_at`        | `GiftDate`     | DateTime | Yes      | Date formatting                    |
| `owner` (donor\_id) | `ContactId`    | Integer  | Yes      | Contact reference mapping          |
| `status`            | `GiftStatus`   | String   | No       | Status enumeration                 |
| `source_type`       | `GiftType`     | String   | No       | Payment method mapping             |
| `fee_amount`        | `Fee`          | Decimal  | No       | Processing fees (cents to dollars) |

### Extended Fields

| WeGive Field | Virtuous Field | Transformation      | Notes                          |
| ------------ | -------------- | ------------------- | ------------------------------ |
| `currency`   | `CurrencyCode` | Direct mapping      | Defaults to USD                |
| `reference`  | `Reference`    | Reference tracking  | Transaction ID or check number |
| `memo`       | `Note`         | Direct mapping      | Internal notes or memo         |
| `fund_id`    | `ProjectId`    | Project correlation | Primary project designation    |

## Gift Types and Categories

### Standard Gift Processing

**Donation Gift Mapping:**

* **Amount**: Converted from cents to dollars with proper decimal formatting
* **Date**: Transaction date converted to Virtuous date format
* **Contact Reference**: Linked to appropriate Virtuous contact based on integration version
* **Project**: Mapped to corresponding Virtuous project for fund designation
* **Payment Method**: Converted to appropriate Virtuous gift type

### Recurring Gift Transactions

**Recurring Gift Processing:**

* **Schedule Reference**: Links to RecurringGift object in Virtuous
* **Sequence Tracking**: Maintains order in recurring gift series
* **Amount Consistency**: Ensures amount matches recurring gift schedule
* **Project Alignment**: Uses project from recurring gift configuration

### Pledge Payment Processing

**Pledge Payment Handling:**

* **Pledge Reference**: Links to existing pledge commitment
* **Payment Sequence**: Tracks payment number in pledge series
* **Balance Tracking**: Updates pledge balance automatically
* **Project Designation**: Inherits project from pledge setup

## Payment Method Mapping

### Source Type Transformation

| WeGive Source Type | Virtuous Gift Type | Description                |
| ------------------ | ------------------ | -------------------------- |
| `card`             | `CreditCard`       | Credit/debit card payments |
| `bank`             | `ACH`              | Electronic fund transfers  |
| `check`            | `Check`            | Check payments             |
| `cash`             | `Cash`             | Cash donations             |
| `venmo`            | `DigitalWallet`    | Venmo payments             |
| `paypal`           | `DigitalWallet`    | PayPal payments            |
| `crypto`           | `Cryptocurrency`   | Cryptocurrency donations   |
| `stock`            | `Stock`            | Stock/securities donations |
| `wire`             | `WireTransfer`     | Wire transfer payments     |
| `other`            | `Other`            | Unknown or other methods   |

### Payment Method Processing

**Payment Type Rules:**

* Default to most appropriate Virtuous gift type
* Maintain payment method for reporting purposes
* Handle special payment types (crypto, stock) appropriately
* Support custom payment method mapping

## Project Designation Mapping

### Single Project Designation

**Simple Project Assignment:**

* WeGive fund maps directly to Virtuous project
* Project ID correlation maintained through integration
* Default project used when no specific designation provided
* Project validation ensures active status

### Multiple Project Allocations

**Split Gift Handling:**

* WeGive fund allocations map to multiple Virtuous designations
* Allocation amounts distributed across projects
* Percentage-based or amount-based splits supported
* Total validation ensures gift amount accuracy

### Default Project Management

**No Project Specified:**

* Uses configured default project ID from integration settings
* Ensures all gifts have proper project designation
* Prevents gift creation failures due to missing projects
* Supports organizational default fund strategies

## Contact Reference Mapping

### V1 Contact Reference

**Direct Contact Mapping:**

* WeGive donor ID maps to Virtuous contact ID
* Simple one-to-one relationship
* Contact validation ensures donor exists in Virtuous
* Direct contact ID correlation

### V2 Enhanced Contact Reference

**Hierarchical Contact Mapping:**

* WeGive donor maps to ContactIndividual within Contact
* Contact hierarchy maintained for gift attribution
* Primary individual designation for household gifts
* Organization contact handling for corporate gifts

#### V2 Contact Resolution

**Individual Gifts:**

* Attribute to specific ContactIndividual
* Maintain household relationship context
* Primary individual designation when appropriate
* Personal vs. household gift distinction

**Household Gifts:**

* Attribute to household Contact when appropriate
* Coordinate with primary individual
* Shared gift recognition and acknowledgment
* Family giving pattern tracking

## Data Transformation

### Amount Processing

**Currency Conversion:**

* Convert from cents to dollars with 2 decimal precision
* Handle international currency when applicable
* Maintain precision for accounting accuracy
* Support currency-specific formatting

### Date Processing

**Date Handling:**

* Convert UTC timestamps to Virtuous date format
* Respect organization timezone settings
* Handle date-only vs. datetime fields appropriately
* Maintain chronological accuracy

### Status Mapping

**Transaction Status Processing:**

* Success → Completed gift status
* Refunded → Reversed or refunded gift status
* Failed → Not synced to Virtuous
* Pending → Held for manual review

## Sync Operations

### Individual Gift Processing

#### Push Operation (WeGive → Virtuous)

**Create New Gift:**

* Validate all required fields are present
* Ensure contact exists in Virtuous (create if needed)
* Map payment method to appropriate gift type
* Assign to correct project designation
* Create gift with complete information
* Store correlation ID for future updates

**Update Existing Gift:**

* Use correlation ID for gift identification
* Update amount, date, or project if changed
* Handle status changes (refunds, corrections)
* Maintain gift history and audit trail

#### Pull Operation (Virtuous → WeGive)

**Import Gift:**

* Map Virtuous gift fields to WeGive transaction structure
* Resolve contact reference to WeGive donor
* Convert amount and date to WeGive format
* Create or update WeGive transaction record
* Store correlation ID for bidirectional sync

### Batch Processing

#### Enhanced Batch Operations

**Batch Gift Creation:**

* Process multiple gifts in single API call
* Optimize API usage for large transaction volumes
* Maintain transaction order and relationships
* Handle batch-level error reporting

**Batch Processing Benefits:**

* Improved performance for large data sets
* Reduced API call volume
* Enhanced error handling and reporting
* Coordinated gift creation for events

#### Daily Batch Jobs

**Scheduled Processing:**

* Daily batch jobs for bulk transaction sync
* Off-peak processing to minimize impact
* Comprehensive error handling and retry logic
* Performance monitoring and optimization

## Validation and Error Handling

### Data Validation

**Required Field Validation:**

* Amount must be positive value
* Gift date is required and valid
* Contact reference must exist
* Project reference must be valid and active

**Business Rule Validation:**

* Gift amount reasonable for donor profile
* Date within acceptable range
* Payment method appropriate for amount
* Project designation allowed for gift type

### Error Handling

**Common Gift Errors:**

* Invalid contact reference
* Missing or inactive project
* Amount format errors
* Date validation failures

**Error Recovery:**

* Automatic retry for transient failures
* Contact creation for missing donors
* Default project assignment when needed
* Manual review queue for complex issues

## Performance Optimization

### Individual vs. Batch Processing

**Individual Gift Processing:**

* Real-time processing for immediate sync
* Individual error handling and resolution
* Immediate feedback for gift processing
* Lower throughput but immediate results

**Batch Processing Advantages:**

* Higher throughput for large volumes
* Efficient API usage
* Coordinated error handling
* Optimized for daily processing workflows

### Processing Strategies

**Real-time Processing:**

* High-priority gifts processed immediately
* Major gift notifications
* Event-based gift processing
* Immediate donor acknowledgment needs

**Batch Processing:**

* Regular donations processed in daily batches
* Historical data imports
* Bulk gift corrections
* Periodic reconciliation

## Gift Recognition and Acknowledgment

### Acknowledgment Coordination

**Gift Recognition:**

* Coordinate acknowledgment between systems
* Maintain donor communication preferences
* Support custom acknowledgment workflows
* Track acknowledgment status

**Tax Receipt Management:**

* Support tax-deductible gift tracking
* Coordinate receipt generation
* Maintain gift tax status
* Support receipt resend capabilities

## Integration with Recurring Gifts

### Recurring Gift Relationship

**Recurring Gift Tracking:**

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

### Schedule Management

**Recurring Gift Coordination:**

* Schedule changes reflected in individual gifts
* Amount modifications tracked appropriately
* Payment method updates coordinated
* Project changes applied to future gifts

## Special Gift Types

### In-Kind Gifts

**Non-Cash Gift Handling:**

* Special processing for in-kind donations
* Value assessment and tracking
* Appropriate tax treatment
* Description and documentation

### Planned Gifts

**Planned Gift Processing:**

* Estate gift tracking and processing
* Beneficiary designation management
* Value realization timing
* Special recognition requirements

### Corporate Gifts

**Organization Gift Handling:**

* Corporate contact attribution
* Employee matching gift coordination
* Corporate foundation gift tracking
* Business relationship maintenance

This comprehensive gift mapping ensures accurate financial transaction synchronization between WeGive and Virtuous while supporting various gift types, processing methods, and integration versions for optimal donation management.