> ## 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 field mapping between WeGive transactions and Blackbaud Raiser's Edge NXT gifts

# Gift Data Mapping

This document details the field-level mappings between WeGive transaction records and Blackbaud Raiser's Edge NXT gift records.

## Object Overview

### WeGive Transaction Object

* **Purpose**: Represents donations and payments processed through WeGive platform
* **API Endpoint**: `/transactions/{transaction}`
* **Unique Identifier**: WeGive transaction ID
* **Payment Processing**: Includes payment method, status, and processing details

### Blackbaud Gift Object

* **Purpose**: Represents donations, pledges, and other contributions in Raiser's Edge NXT
* **API Endpoint**: `gift/v1/gifts/{gift_id}`
* **Unique Identifier**: Blackbaud gift ID
* **Financial Management**: Includes fund designations, recognition, and stewardship

## Core Gift Mapping

### Basic Gift Information

| WeGive Field       | Blackbaud Field        | Data Type | Direction | Required | Notes                               |
| ------------------ | ---------------------- | --------- | --------- | -------- | ----------------------------------- |
| `id`               | Correlation ID storage | String    | Both      | No       | Stored in custom field or reference |
| `amount`           | `amount.value`         | Decimal   | Both      | Yes      | Gift amount in dollars              |
| `currency`         | `amount.currency`      | String    | Both      | No       | Default "USD"                       |
| `created_at`       | `date`                 | DateTime  | Both      | Yes      | Gift date, timezone converted       |
| `status`           | Gift status            | String    | Both      | No       | Completed, Pending, Failed          |
| `reference_number` | `reference`            | String    | Both      | No       | External reference or check number  |

### Donor and Constituency

| WeGive Field | Blackbaud Field          | Data Type | Direction | Required | Notes                       |
| ------------ | ------------------------ | --------- | --------- | -------- | --------------------------- |
| `owner.id`   | `constituent_id`         | String    | Both      | Yes      | Links to constituent record |
| `owner.type` | Derived from constituent | String    | Both      | No       | Individual or Organization  |
| `owner.name` | Derived from constituent | String    | Both      | No       | Display name for gift       |

### Payment Method Mapping

| WeGive Payment Method | Blackbaud Payment Method | Description                     |
| --------------------- | ------------------------ | ------------------------------- |
| `card`                | `CreditCard`             | Credit and debit card payments  |
| `bank`                | `DirectDebit`            | Bank transfers and ACH          |
| `check`               | `PersonalCheck`          | Physical and electronic checks  |
| `cash`                | `Cash`                   | Cash donations                  |
| `wire`                | `WireTransfer`           | Wire transfers                  |
| `paypal`              | `OnlinePayment`          | PayPal and digital wallets      |
| `venmo`               | `OnlinePayment`          | Venmo and peer-to-peer payments |
| `other`               | `Other`                  | Other payment methods           |

### Gift Type Classification

| WeGive Transaction Type | Blackbaud Gift Type    | Sub Type      | Notes                             |
| ----------------------- | ---------------------- | ------------- | --------------------------------- |
| `donation`              | `Donation`             | `Cash`        | Standard one-time donation        |
| `recurring`             | `RecurringGiftPayment` | `Pledge`      | Payment from recurring schedule   |
| `pledge_payment`        | `PledgePayment`        | `Installment` | Payment toward pledge commitment  |
| `grant`                 | `Grant`                | `Foundation`  | Foundation or institutional grant |
| `tribute`               | `Donation`             | `Memorial`    | Memorial or honor gift            |
| `matching`              | `MatchingGift`         | `Corporate`   | Corporate matching gift           |

## Fund Designation Mapping

### 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 gift 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         |
| `fund_allocations[].percentage` | Calculated                | Decimal   | Both      | No       | Percentage of total gift |

**Example Multi-Fund Gift Structure (Blackbaud)**

```json theme={null}
{
  "amount": {"value": 100.00, "currency": "USD"},
  "designations": [
    {
      "fund_id": "fund-123",
      "amount": {"value": 75.00, "currency": "USD"}
    },
    {
      "fund_id": "fund-456", 
      "amount": {"value": 25.00, "currency": "USD"}
    }
  ]
}
```

## Campaign and Appeal Attribution

### Campaign Tracking

| 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 |
| `appeal.name`   | `appeals[0].name`          | String    | Both      | No       | Appeal display name             |

### Marketing Attribution

| WeGive Field   | Blackbaud Field  | Data Type | Direction | Required | Notes                     |
| -------------- | ---------------- | --------- | --------- | -------- | ------------------------- |
| `source`       | `source_code`    | String    | Both      | No       | Marketing source tracking |
| `medium`       | Custom attribute | String    | Both      | No       | Marketing medium          |
| `utm_campaign` | Custom attribute | String    | Both      | No       | UTM campaign parameter    |
| `utm_source`   | Custom attribute | String    | Both      | No       | UTM source parameter      |
| `utm_medium`   | Custom attribute | String    | Both      | No       | UTM medium parameter      |

## Gift Recognition and Acknowledgment

### Acknowledgment Preferences

| WeGive Field   | Blackbaud Field      | Data Type | Direction | Required | Notes                           |
| -------------- | -------------------- | --------- | --------- | -------- | ------------------------------- |
| `anonymous`    | `anonymous`          | Boolean   | Both      | No       | Anonymous gift preference       |
| `no_thank_you` | `do_not_acknowledge` | Boolean   | Both      | No       | Skip acknowledgment             |
| `tribute_type` | `tribute.type`       | String    | Both      | No       | Memorial, Honor, Celebration    |
| `tribute_name` | `tribute.name`       | String    | Both      | No       | Person being honored/remembered |

### Stewardship Information

| WeGive Field            | Blackbaud Field    | Data Type | Direction | Required | Notes                   |
| ----------------------- | ------------------ | --------- | --------- | -------- | ----------------------- |
| `thank_you_sent`        | `acknowledged`     | Boolean   | Both      | No       | Acknowledgment status   |
| `thank_you_date`        | `acknowledge_date` | Date      | Both      | No       | When thank you was sent |
| `tax_receipt_sent`      | `receipted`        | Boolean   | Both      | No       | Tax receipt status      |
| `tax_receipt_date`      | `receipt_date`     | Date      | Both      | No       | When receipt was issued |
| `tax_deductible_amount` | `receipt_amount`   | Decimal   | Both      | No       | Deductible portion      |

## Soft Credits and Recognition

### Soft Credit Tracking

| WeGive Field                    | Blackbaud Field                  | Data Type | Direction | Required | Notes                          |
| ------------------------------- | -------------------------------- | --------- | --------- | -------- | ------------------------------ |
| `soft_credits`                  | `soft_credits`                   | Array     | Both      | No       | Additional recognition credits |
| `soft_credits[].constituent_id` | `soft_credits[n].constituent_id` | String    | Both      | Yes      | Person receiving soft credit   |
| `soft_credits[].amount`         | `soft_credits[n].amount`         | Decimal   | Both      | No       | Soft credit amount             |
| `soft_credits[].type`           | `soft_credits[n].type`           | String    | Both      | No       | Solicitor, Volunteer, etc.     |

### Joint Gift Recognition

| WeGive Field        | Blackbaud Field         | Data Type | Direction | Required | Notes                           |
| ------------------- | ----------------------- | --------- | --------- | -------- | ------------------------------- |
| `joint_donors`      | Additional constituents | Array     | Both      | No       | Multiple donors for single gift |
| `primary_donor`     | Primary constituent     | String    | Both      | Yes      | Main donor for gift record      |
| `joint_recognition` | Recognition credits     | Array     | Both      | No       | Recognition for all donors      |

## Recurring Gift Integration

### Recurring Gift Schedule

| WeGive Field            | Blackbaud Field       | Data Type | Direction | Required | Notes                            |
| ----------------------- | --------------------- | --------- | --------- | -------- | -------------------------------- |
| `recurring_donation_id` | `recurring_gift_id`   | String    | Both      | No       | Links to recurring gift schedule |
| `installment_number`    | `installment`         | Integer   | Both      | No       | Sequence number in series        |
| `total_installments`    | Derived from schedule | Integer   | Both      | No       | Total expected payments          |

### Pledge Integration

| WeGive Field            | Blackbaud Field | Data Type | Direction | Required | Notes                      |
| ----------------------- | --------------- | --------- | --------- | -------- | -------------------------- |
| `pledge_id`             | `pledge_id`     | String    | Both      | No       | Links to pledge commitment |
| `pledge_balance`        | Calculated      | Decimal   | Both      | No       | Remaining pledge balance   |
| `pledge_payment_number` | `installment`   | Integer   | Both      | No       | Payment sequence number    |

## Processing and Financial Details

### Transaction Processing

| WeGive Field          | Blackbaud Field          | Data Type | Direction | Required | Notes                    |
| --------------------- | ------------------------ | --------- | --------- | -------- | ------------------------ |
| `processor`           | `payment_method_details` | String    | Both      | No       | Payment processor used   |
| `processor_fee`       | `fees`                   | Decimal   | Both      | No       | Processing fees          |
| `net_amount`          | `net_amount`             | Decimal   | Both      | No       | Amount after fees        |
| `processor_reference` | `external_reference`     | String    | Both      | No       | Processor transaction ID |

### Bank and Check Details

| WeGive Field     | Blackbaud Field  | Data Type | Direction | Required | Notes                 |
| ---------------- | ---------------- | --------- | --------- | -------- | --------------------- |
| `check_number`   | `check_number`   | String    | Both      | No       | Physical check number |
| `check_date`     | `check_date`     | Date      | Both      | No       | Date on check         |
| `bank_name`      | `bank_name`      | String    | Both      | No       | Bank name for check   |
| `routing_number` | `routing_number` | String    | Both      | No       | Bank routing number   |
| `account_number` | `account_number` | String    | Both      | No       | Masked account number |

## Custom Fields and Attributes

### Gift Attributes

| WeGive Field     | Blackbaud Field  | Data Type | Direction | Required | Notes                        |
| ---------------- | ---------------- | --------- | --------- | -------- | ---------------------------- |
| `custom_fields`  | `attributes`     | Object    | Both      | No       | Organization-specific fields |
| `tags`           | `gift_codes`     | Array     | Both      | No       | Gift categorization codes    |
| `notes`          | `notes`          | Array     | Both      | No       | Free-form text notes         |
| `internal_notes` | `internal_notes` | Array     | Both      | No       | Staff-only notes             |

### Event and Fundraiser Integration

| WeGive Field        | Blackbaud Field       | Data Type | Direction | Required | Notes                          |
| ------------------- | --------------------- | --------- | --------- | -------- | ------------------------------ |
| `event_id`          | `event_id`            | String    | Both      | No       | Associated event or fundraiser |
| `table_purchase`    | `event_participation` | Object    | Both      | No       | Event table or ticket details  |
| `sponsorship_level` | `sponsorship`         | String    | Both      | No       | Sponsorship tier               |

## Data Transformation Rules

### Amount Handling

**Currency Conversion**

* All amounts stored in dollars (USD) by default
* Multi-currency support available
* Exchange rates captured at time of gift
* Historical rate preservation for reporting

**Precision Rules**

* Dollar amounts rounded to 2 decimal places
* Large gifts (>\$1M) maintain full precision
* Fee calculations preserve all decimal places
* Percentage calculations rounded to 4 places

### Date and Time Processing

**Timezone Handling**

* Gift dates stored in donor's local timezone when available
* UTC conversion for cross-system compatibility
* Daylight saving time adjustments applied
* Historical date preservation for reporting

**Date Field Mapping**

* `created_at` → Gift date (when gift was made)
* `processed_at` → Process date (when gift was processed)
* `deposited_at` → Deposit date (when funds were deposited)

### Status Mapping

| WeGive Status | Blackbaud Status | Description                 |
| ------------- | ---------------- | --------------------------- |
| `completed`   | `Active`         | Successfully processed gift |
| `pending`     | `Pending`        | Gift awaiting processing    |
| `failed`      | `Inactive`       | Failed or rejected gift     |
| `refunded`    | `Reversed`       | Refunded or reversed gift   |
| `disputed`    | `Held`           | Disputed or under review    |

## Sync Behavior

### Create Operations

**New WeGive Transaction → Blackbaud Gift**

1. Validate gift data and requirements
2. Map payment method and amount
3. Link to existing constituent
4. Apply fund designations
5. Create gift record in Blackbaud
6. Store correlation ID for future updates
7. Process any soft credits or attributions

**New Blackbaud Gift → WeGive Transaction**

1. Extract gift and constituent information
2. Map to WeGive transaction format
3. Create or link to WeGive donor
4. Preserve fund and campaign attributions
5. Store correlation ID

### Update Operations

**Bidirectional Updates**

* Gift amount and designation changes
* Payment method updates
* Recognition and acknowledgment status
* Notes and attribute modifications
* Soft credit additions or changes

**Restricted Updates**

* Gift date typically immutable after creation
* Constituent linkage requires administrative approval
* Major amount changes may require audit trail
* Status changes follow business rules

### Delete and Void Operations

**Gift Reversal**

* WeGive refunds create reversed gift records
* Blackbaud gift reversals update status
* Audit trail preserved for all changes
* Financial reporting adjustments applied

## API Examples

### Create Gift Record

**WeGive to Blackbaud Gift Creation**

```json theme={null}
POST /gift/v1/gifts
{
  "constituent_id": "280bb97a-f71e-4158-9040-85506f6c2e8e",
  "type": "Donation",
  "subtype": "Cash",
  "amount": {
    "value": 250.00,
    "currency": "USD"
  },
  "date": "2024-03-15T10:30:00Z",
  "payment_method": "CreditCard",
  "designations": [
    {
      "fund_id": "f1e8c4a7-2b5d-4c91-8e72-1a3b4c5d6e7f",
      "amount": {
        "value": 250.00,
        "currency": "USD"
      }
    }
  ],
  "appeals": [
    {
      "campaign_id": "c123-4567-8901-2345",
      "appeal_id": "a987-6543-2109-8765"
    }
  ],
  "reference": "WG-TXN-123456"
}
```

### Update Gift Acknowledgment

**Blackbaud to WeGive Acknowledgment Sync**

```json theme={null}
PUT /transactions/{transaction_id}
{
  "thank_you_sent": true,
  "thank_you_date": "2024-03-20T14:00:00Z",
  "tax_receipt_sent": true,
  "tax_receipt_date": "2024-03-20T14:00:00Z",
  "tax_deductible_amount": 250.00,
  "blackbaud_gift_id": "12345678-1234-1234-1234-123456789abc"
}
```

### Multi-Fund Gift Example

**Complex Gift with Multiple Designations**

```json theme={null}
{
  "amount": {"value": 1000.00, "currency": "USD"},
  "designations": [
    {
      "fund_id": "general-fund",
      "amount": {"value": 600.00, "currency": "USD"},
      "percentage": 60.0
    },
    {
      "fund_id": "building-fund", 
      "amount": {"value": 300.00, "currency": "USD"},
      "percentage": 30.0
    },
    {
      "fund_id": "scholarship-fund",
      "amount": {"value": 100.00, "currency": "USD"},
      "percentage": 10.0
    }
  ],
  "soft_credits": [
    {
      "constituent_id": "spouse-id",
      "amount": {"value": 1000.00, "currency": "USD"},
      "type": "Joint Gift Credit"
    }
  ]
}
```

## Error Handling and Validation

### Required Field Validation

**Critical Fields**

* Constituent ID must exist and be valid
* Gift amount must be positive
* Gift date cannot be in the future
* At least one fund designation required
* Payment method must be valid type

**Data Quality Checks**

* Amount precision validation (2 decimal places)
* Date format validation (ISO 8601)
* Currency code validation (3-letter codes)
* Fund ID existence verification
* Constituent relationship validation

### Common Error Scenarios

**Invalid Constituent**

* Error: Constituent ID not found
* Resolution: Create constituent first or use valid ID
* Action: Queue gift for manual review

**Fund Validation Errors**

* Error: Fund ID invalid or inactive
* Resolution: Map to default fund or create fund
* Action: Log warning and use fallback fund

**Amount Validation Issues**

* Error: Negative or zero amount
* Resolution: Skip transaction or flag for review
* Action: Log error and notify administrators

### Retry and Recovery Logic

**Temporary Failures**

* Network timeouts: Retry with exponential backoff
* Rate limiting: Respect retry-after headers
* Server errors: Retry up to 3 times with increasing delays

**Permanent Failures**

* Validation errors: Log and skip record
* Authorization errors: Alert system administrators
* Data conflicts: Queue for manual resolution

## Performance Optimization

### Batch Processing

**Gift Creation Batches**

* Process up to 100 gifts per API call
* Group by constituent for efficiency
* Parallel processing for independent gifts
* Progress tracking and status reporting

**Update Optimization**

* Delta sync for changed records only
* Timestamp-based change detection
* Bulk update operations where supported
* Minimized API calls through intelligent batching

### Caching Strategies

**Reference Data Caching**

* Fund information cached for 1 hour
* Campaign data cached for 30 minutes
* Constituent lookups cached for 15 minutes
* Payment method mappings cached indefinitely

**Performance Monitoring**

* Average gift sync time tracking
* API response time monitoring
* Error rate alerting
* Throughput optimization

## Reporting and Analytics

### Gift Analytics

**Sync Metrics**

* Total gifts synchronized per period
* Success/failure rates by gift type
* Average sync time per gift
* Peak processing times

**Data Quality Metrics**

* Validation error rates
* Missing required field frequency
* Fund mapping accuracy
* Constituent linking success rates

### Financial Reconciliation

**Amount Reconciliation**

* Total gift amounts by period
* Currency conversion accuracy
* Fee calculation validation
* Multi-fund designation accuracy

**Audit Trail Maintenance**

* Complete change history
* User attribution for modifications
* System-generated change timestamps
* Compliance audit support

## Best Practices

### Data Management

1. **Clean Source Data**: Validate transaction data before sync
2. **Consistent Mapping**: Maintain standardized fund and campaign mapping
3. **Regular Reconciliation**: Compare financial totals between systems
4. **Backup Strategy**: Maintain gift data backups before major changes

### Performance Optimization

1. **Batch Operations**: Use batch processing for bulk gift imports
2. **Rate Limiting**: Respect API limits and implement proper throttling
3. **Caching**: Cache frequently accessed reference data
4. **Monitoring**: Track sync performance and optimize bottlenecks

### Security and Compliance

1. **Data Encryption**: Encrypt sensitive gift data in transit and at rest
2. **Access Control**: Limit gift data access to authorized personnel
3. **Audit Logging**: Maintain comprehensive audit trails
4. **Compliance**: Follow PCI DSS and other applicable regulations

## Troubleshooting Guide

### Common Sync Issues

**Gift Creation Failures**

* Verify constituent exists in both systems
* Check fund ID validity and active status
* Validate gift amount and currency format
* Confirm payment method mapping accuracy

**Amount Discrepancies**

* Review currency conversion rates
* Check fee calculation methods
* Validate multi-fund designation totals
* Verify decimal precision handling

**Date and Time Issues**

* Confirm timezone settings
* Check date format compliance
* Validate date range restrictions
* Review daylight saving time handling

### Data Quality Problems

**Missing Gift Data**

* Check field mapping completeness
* Verify data availability in source system
* Review sync scope and filtering rules
* Validate required field population

**Incorrect Attribution**

* Review campaign and appeal mapping
* Check fund designation accuracy
* Validate soft credit assignments
* Confirm marketing source attribution

### Performance Issues

**Slow Gift Processing**

* Optimize batch sizes for gift volume
* Review API response times
* Check network connectivity
* Monitor system resource usage

**High Error Rates**

* Analyze error pattern trends
* Review data validation rules
* Check system capacity limits
* Validate integration configuration

## Support Resources

### Documentation References

* [Blackbaud Gift API Documentation](https://developer.blackbaud.com/skyapi/docs/services/56b76470069a0509c8f1c5b3/operations/56b76470069a0509c8f1c5b4)
* [WeGive Transaction API Documentation](https://api.wegive.com/docs/transactions)
* [Fund Mapping Documentation](/blackbaud/data-mapping/fund)
* [Campaign Mapping Documentation](/blackbaud/data-mapping/campaign)

### Support Contacts

* **WeGive Support**: [support@wegive.com](mailto:support@wegive.com)
* **Blackbaud Developer Support**: [Developer Community](https://community.blackbaud.com/developer)
* **Integration Specialists**: Available for complex gift mapping scenarios