> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wegive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Options

> Detailed configuration settings and options for the WeGive Planning Center integration

# Configuration Options

The WeGive Planning Center integration has a small, fixed set of dashboard-editable settings — an authentication method, a default fund, and per-object push/pull toggles for donors, funds, and transactions. There is no recurring-donations toggle, no configurable rate-limit/retry/timeout values, and no performance-monitoring or batch-reporting settings — those aren't implemented.

## Authentication Configuration

### Authentication Methods

| Setting | Type | Required | Description |
| - | - | - | - |
| **Enabled** | Boolean | Yes | Master toggle to enable/disable the entire integration |

#### OAuth 2.0 Configuration (Recommended)

| Setting | Type | Required | Description |
| - | - | - | - |
| **Client ID** | String | Yes | OAuth Client ID from Planning Center application |
| **Client Secret** | String | Yes | OAuth Client Secret from Planning Center application |
| **Scope** | String | Auto | Automatically set to 'people giving' |

**OAuth Benefits:**

* Token-based authentication with automatic refresh (checked and refreshed proactively on every API call, not just on failure)

#### Legacy Authentication Configuration

| Setting | Type | Required | Description |
| - | - | - | - |
| **Application ID** | String | Yes | Planning Center Application ID |
| **Application Secret** | String | Yes | Planning Center Personal Access Token |

**Legacy Use Cases:**

* Existing implementations using basic authentication
* Simple setup without OAuth flow complexity

## Synchronization Controls

### Data Type Configuration

There are exactly six push/pull toggles, one pair per object type. There is no separate toggle for recurring/scheduled donations — Planning Center's integration doesn't sync a recurring-gift object at all.

#### Donors/People Sync

| Setting | Default | Description |
| - | - | - |
| **Push Donors** | Enabled | Send WeGive donors to Planning Center as people |
| **Pull Donors** | Enabled | Import Planning Center people to WeGive as donors |

**Push Donors:**

* Creates person records in Planning Center from WeGive donors (matched by a stored `planning_center_id` only — no email/name matching)
* Syncs contact information (emails, phones, addresses) after create or update
* If an update targets a Planning Center person that no longer exists (404), the integration clears the stale ID and creates a new person rather than failing

**Pull Donors:**

* Imports Planning Center people to WeGive

#### Transactions/Donations Sync

| Setting | Default | Description |
| - | - | - |
| **Push Transactions** | Enabled | Send WeGive donations to Planning Center as donations |
| **Pull Transactions** | Enabled | Import Planning Center donations to WeGive |

**Push Transactions:**

* Runs once daily (8:01 AM) as a single batch job — there is no real-time/immediate push path
* Finds or creates a single recurring "WeGive"-named batch and a single "WeGive"-named payment source
* Each transaction gets exactly one fund designation — split/multi-fund gifts aren't supported
* If any part of the run throws, the whole batch is rolled back: any `planning_center_id`s set during that run are cleared and the partial batch is deleted in Planning Center

**Pull Transactions:**

* Imports Planning Center donations to WeGive

#### Funds Sync

| Setting | Default | Description |
| - | - | - |
| **Push Funds** | Enabled | Send WeGive funds to Planning Center as funds |
| **Pull Funds** | Enabled | Import Planning Center funds to WeGive |

**Fund Sync:**

* Push finds-or-creates a Planning Center fund by matching `name`; on create it also sends `description`, a fixed `visibility: everywhere`, and a fixed `color_identifier: 1` — but an existing fund is never updated after the initial match/create, so later WeGive-side name/description edits don't propagate
* Pull imports `name`, `description`, and `created_at`; a Planning Center fund with `visibility: hidden` is soft-deleted in WeGive automatically

## Advanced Settings

### Required Configuration

| Setting | Type | Required | Description |
| - | - | - | - |
| **Default Fund ID** | String | Yes | Planning Center fund ID for donations without specific designation |

**Important Notes:**

* Used when a transaction has no fund set; if there's still no `default_fund_id`, the integration falls back to the destination organization's oldest fund with a `planning_center_id`
* If no fund can be resolved at all, that transaction throws `Unknown Fund Source` and is skipped (reported to Sentry, not a full-batch failure)

### Batch Processing

Daily batches run automatically at 8:01 AM and commit automatically on success — there's no manual/scheduled-time configuration option and no separate "batch commitment" setting; a batch always auto-commits after processing.

### API Rate Limiting

Planning Center's own limit is 70 requests per 20 seconds. WeGive's integration proactively throttles to this internally — it isn't a dashboard-configurable setting, and there's no separate configurable retry count or request timeout.

## Data Flow Configuration

### Sync Direction Matrix

| Data Type | Push (WeGive → Planning Center) | Pull (Planning Center → WeGive) |
| - | - | - |
| **Donors/People** | Configurable | Configurable |
| **Transactions/Donations** | Configurable | Configurable |
| **Funds** | Configurable | Configurable |

## Payment Source

All WeGive transactions post to a single Planning Center payment source named "WeGive" — the integration finds it by name or creates it automatically; there's no configuration option to change this name or use multiple payment sources.

## Fund Assignment

**Fund Assignment Priority (fixed, not configurable):**

1. Use the transaction's own linked fund (if it has a `planning_center_id`)
2. Fall back to the integration's `default_fund_id`
3. Fall back to the destination organization's oldest fund with a `planning_center_id`
4. If none resolve, the transaction throws `Unknown Fund Source` and is skipped

There's no fund-creation toggle, hidden-fund-handling setting, or fund-validation strictness setting — but the underlying behavior isn't configurable-off either: pushing a fund with no `planning_center_id` always looks it up by name in Planning Center and creates it there automatically if no match exists (`visibility: everywhere`). On the pull side, a Planning Center fund whose `visibility` is `hidden` is soft-deleted in WeGive automatically — this happens unconditionally, not via a "Hidden Fund Handling: Skip/Include" setting.

## Configuration Best Practices

### Initial Setup

1. **Choose OAuth 2.0**: Recommended for new implementations
2. **Test Thoroughly**: Confirm the connection before enabling sync
3. **Set a Default Fund**: Required to avoid `Unknown Fund Source` skips
4. **Monitor Closely**: Watch `integration_logs` during the first week — sync failures aren't surfaced to the dashboard or the customer

### Ongoing Management

1. **Regular Reviews**: Check `enabled`/OAuth validity and `default_fund_id` periodically
2. **Error Analysis**: Review `integration_logs` for `error-execution` rows and Sentry for `Unknown Fund Source` exceptions — neither generates a customer-facing notification

### Security Considerations

1. **Credential Rotation**: OAuth tokens refresh automatically; legacy app\_id/app\_secret should be rotated manually if compromised
2. **Access Control**: Limit who can modify integration settings

## Troubleshooting Configuration Issues

### Common Problems

**Issue**: Authentication failures

* **Check**: Verify OAuth credentials or legacy app\_id/app\_secret are correct
* **Check**: `integration_logs` rows with `status = 'error-execution'` and an OAuth-related `details.error`

**Issue**: Batch processing failures / transactions not syncing

* **Check**: Verify `default_fund_id` is valid and active
* **Check**: Sentry for `Unknown Fund Source` exceptions on specific transactions (a per-transaction skip, not a full-batch failure)

**Issue**: Duplicate contact records

* **Cause**: Matching is by `planning_center_id` only — a donor pushed before ever being linked to an existing Planning Center person will create a new one
* **Solution**: Clean duplicates in Planning Center before initial sync; ensure donors are matched/linked before their first push

### Configuration Validation

**Required Settings Check:**

* Authentication credentials are valid and tested
* `default_fund_id` exists and is active in Planning Center
* Push/pull toggles reflect the intended sync direction per object type

This integration's configuration surface is intentionally small — six push/pull toggles, one default fund, and an authentication method. There is no dashboard control for rate limiting, retries, timeouts, logging detail, or recurring-donation sync.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.