> ## 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. # Integration Nuances > Important considerations and behaviors of the WeGive Planning Center integration # Integration Nuances This document outlines important behaviors, limitations, and considerations when using the WeGive Planning Center integration, including specific features of the People and Giving modules. ## Authentication Behaviors ### OAuth 2.0 Flow **Authentication Process:** * Initial OAuth authorization redirects to Planning Center * User grants permission for 'people giving' scopes * Authorization code exchanged for access and refresh tokens * Automatic token refresh without user intervention **Token Management:** * Access tokens automatically refreshed before expiration * Refresh tokens stored securely for ongoing authentication * Failed token refresh triggers re-authorization flow * Token scope limited to People and Giving modules only ### Legacy Authentication **Basic Auth Process:** * Uses Application ID and Personal Access Token * Direct API authentication without OAuth flow * Manual token rotation required for security * Same scope access as OAuth (people and giving) **Migration Considerations:** * OAuth 2.0 recommended for new implementations * Legacy auth continues to work for existing setups * Migration to OAuth available without data loss ## Data Flow Behaviors ### Daily Batch Processing **WeGive Import Batches:** * Daily batches created automatically at 8:01 AM * Batch name format: "WeGive Import - \[Date]" * All WeGive transactions for the day included in single batch * Automatic batch commitment after successful processing **Batch Processing Logic:** * Transactions grouped by donation date, not processing date * Missing transaction batches detected and created automatically * Failed batch processing triggers rollback of entire batch * Batch status tracked for audit and troubleshooting ### Fund Assignment Logic **Priority Order for Fund Assignment:** 1. **Specific Fund**: Use designated fund from WeGive transaction 2. **Default Fund**: Fall back to configured default fund 3. **Fund Creation**: Create new fund if specified fund doesn't exist 4. **General Fund**: Use organization's general fund as final fallback **Fund Visibility Handling:** * Hidden funds in Planning Center marked as deleted in WeGive * Fund visibility changes sync bidirectionally * Fund creation requires active status in Planning Center * Fund deletion preserves historical transaction references ## Contact Management Behaviors ### Person Record Matching **Matching Strategy (in order of preference):** 1. **Planning Center ID**: Exact match using stored correlation ID 2. **Email Address**: Primary email address matching 3. **Name Matching**: Full name comparison for individuals 4. **Create New**: When no match found **Contact Information Handling:** * Primary email address mapped to main email field * Additional email addresses stored as secondary contacts * Phone numbers categorized by type (mobile, home, work) * Address information synchronized with full geographic data ### Family and Household Relationships **Family Coordination:** * Individual person records maintained separately * Family relationships preserved in Planning Center structure * Household addresses coordinated across family members * Contact preferences managed at individual level ## Payment Source Management ### WeGive Payment Source **Single Payment Source Strategy:** * All WeGive transactions use "WeGive" payment source in Planning Center * Payment method details preserved in transaction metadata * Simplifies Planning Center payment source management * Enables unified reporting across all WeGive payment types **Payment Method Mapping:** * Credit cards, ACH, checks all attributed to "WeGive" source * Original payment method preserved in transaction details * Payment source creation automatic during initial setup * Payment source reused for all subsequent transactions ## API Rate Limiting and Performance ### Planning Center API Limits **Rate Limiting Rules:** * 70 requests per 20-second window * Automatic rate limit detection and compliance * Request queuing during rate limit periods * Intelligent batching to optimize API usage **Performance Optimization:** * Incremental sync for efficiency (only changed data) * Batch operations for bulk data processing * Request optimization to minimize API calls * Background job processing for time-intensive operations ### Large Data Set Handling **Initial Sync Considerations:** * Large datasets may require extended processing time * Progress tracking available for long-running sync operations * Checkpoint system for resuming interrupted syncs * Memory optimization for processing large volumes ## Error Handling and Recovery ### Automatic Error Recovery **Retry Logic:** * Failed API requests automatically retried up to 3 times * Exponential backoff prevents API overload * Different retry strategies for different error types * Manual retry options available for persistent failures **Batch Error Handling:** * Single transaction failure doesn't fail entire batch * Failed transactions quarantined for manual review * Batch rollback capability for critical errors * Comprehensive error logging for troubleshooting ### Common Error Scenarios **Authentication Errors:** * Token expiration handled automatically with refresh * Scope permission errors logged with clear messages * Invalid credentials trigger re-authentication flow * Network connectivity issues handled with retries **Data Validation Errors:** * Missing required fields cause transaction rejection * Invalid fund IDs trigger default fund assignment * Duplicate detection prevents record conflicts * Data format errors logged with specific field information ## Sync Timing and Scheduling ### Daily Processing Schedule **Automated Operations:** * **8:01 AM**: Daily batch generation for previous day's transactions * **8:15 AM**: Pull sync for updated Planning Center data * **Continuous**: Real-time processing for immediate updates (when enabled) * **Weekly**: Comprehensive data validation and cleanup **Manual Sync Options:** * Full sync available for complete data refresh * Incremental sync for recent changes only * Specific date range sync for historical data * Test sync for configuration validation ### Incremental vs. Full Sync **Incremental Sync Benefits:** * Faster processing for daily operations * Lower API usage and better performance * Focuses on recently changed data only * Maintains sync efficiency for ongoing operations **Full Sync Use Cases:** * Initial integration setup * Data quality audits and cleanup * Recovery from extended outages * Configuration changes requiring complete refresh ## Fund and Designation Behaviors ### Fund Creation and Management **Automatic Fund Creation:** * Missing funds created automatically when referenced * Fund names synchronized between systems * Fund descriptions and metadata preserved * Fund status (active/inactive) coordinated **Fund Designation Logic:** * Split designations supported for multiple funds * Designation amounts validated against transaction total * Fund allocation percentages calculated automatically * Undesignated amounts assigned to default fund ### Recurring Gift Coordination **Recurring Gift Processing:** * Planning Center recurring gifts linked to WeGive scheduled donations * Recurring gift schedules synchronized bidirectionally * Individual gifts created from recurring gift schedules * Schedule modifications reflected in both systems ## Data Quality and Validation ### Contact Information Validation **Email Validation:** * Email format validation before sync * Duplicate email detection within organization * Invalid emails logged but don't prevent contact creation * Email preference coordination between systems **Address Standardization:** * Address formatting normalized for consistency * Geographic data validation where possible * International address support with country codes * Address type designation (home, work, mailing) ### Financial Data Validation **Transaction Validation:** * Amount validation ensures positive values * Date validation prevents future-dated transactions * Fund validation confirms fund exists and is active * Currency validation for international organizations ## Reporting and Analytics Integration ### Financial Reporting Coordination **Batch Reporting:** * Daily batch summaries for accounting reconciliation * Transaction counts and totals for validation * Fund allocation reports for designation tracking * Error reports for data quality monitoring **Donor Analytics:** * Giving history synchronized between systems * Donor engagement metrics coordinated * Contact communication history preserved * Giving pattern analysis supported ## Security and Compliance ### Data Privacy Considerations **Information Sharing:** * Only necessary data synchronized between systems * Contact preferences respected in both platforms * Data retention policies coordinated * Privacy compliance maintained across integration **Access Control:** * Integration access limited to configured scopes * API permissions validated during setup * Audit logs maintained for all sync operations * Security monitoring for unusual activity patterns ## Performance Monitoring ### Integration Health Checks **Automated Monitoring:** * Daily batch processing success rates * API response times and error rates * Data sync completion status * Integration performance metrics **Alert Conditions:** * Failed batch processing * Extended API response times * High error rates in data sync * Authentication or permission failures ## Best Practices for Optimal Performance ### Data Management **Regular Maintenance:** * Weekly review of integration logs * Monthly data quality audits * Quarterly configuration reviews * Annual authentication credential rotation **Optimization Strategies:** * Monitor API usage patterns * Optimize sync scheduling for off-peak hours * Regular cleanup of unused or duplicate data * Performance tuning based on usage patterns ### Troubleshooting Preparation **Diagnostic Information:** * Maintain current integration logs * Document configuration changes * Keep backup of critical data * Monitor system performance trends This understanding of integration nuances will help you successfully implement and maintain the WeGive Planning Center integration while avoiding common pitfalls and ensuring optimal performance for your church management needs.