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

> Learn how to configure sync settings and preferences for your DonorDirect integration

# DonorDirect Integration Configuration

Configure your DonorDirect integration settings to control how data
synchronizes between WeGive and StudioEnterprise (SE).

<Warning>
  This integration is not yet enabled for live organizations. The settings
  below reflect the integration as built and reviewed — treat this as a
  preview of what setup will look like, not a currently self-serve dashboard
  flow.
</Warning>

## Access Configuration Settings

1. **Log into** your WeGive Dashboard
2. **Navigate to** Settings > Integrations
3. **Select** DonorDirect Integration
4. **Configure** your sync preferences and credentials

## Basic Configuration

### Environment & Credentials

**`environment` · *string* · default: `proto`**

Which StudioEnterprise environment WeGive connects to — production or a
test/sandbox environment. StudioEnterprise runs a separate host per
environment.

**`base_url` · *string***

Custom StudioEnterprise API host, if your environment doesn't use the
standard host pattern.

**`username` / `password`** or **`api_key`**

Authentication for StudioEnterprise. A personal login (username/password)
works for initial setup and testing; a dedicated service-account API key is
required before enabling scheduled, ongoing sync.

**`enabled` · *boolean* · default: `false`**

Master switch for the integration.

## Synchronization Settings

### Pull (StudioEnterprise → WeGive)

All pull toggles default **on**. Pull uses WeGive's custom read-only data
endpoints and does not write anything back to StudioEnterprise.

| Setting | Default | Syncs |
| - | - | - |
| `pull_donors` | On | Accounts (individuals, organizations, and households) |
| `pull_funds` | On | Projects, as WeGive funds |
| `pull_campaigns` | On | Source Codes, as WeGive campaigns |
| `pull_scheduled_donations` | On | Recurring giving plans |
| `pull_transactions` | On | Gifts |

### Push (WeGive → StudioEnterprise)

<Note>
  **All push toggles default OFF.** Each direction must be explicitly enabled
  per organization — enabling pull alone will never write data back to
  StudioEnterprise. This is a deliberate safety default: a pull-only
  connection can never create or modify records in your CRM.
</Note>

| Setting | Default | Syncs |
| - | - | - |
| `push_donors` | Off | New/updated WeGive donors as StudioEnterprise accounts |
| `push_transactions` | Off | Settled WeGive gifts as StudioEnterprise transactions (includes refunds automatically, tied to the same toggle) |
| `push_scheduled_donations` | Off | WeGive recurring plans as StudioEnterprise recurring records |

<Warning>
  Gifts pushed to StudioEnterprise are recorded as **already-processed** —
  WeGive does not ask StudioEnterprise to charge the donor again. Payment
  processing happens in WeGive; the push is a record-keeping sync only.
</Warning>

## Write-Side Configuration (required if any push toggle is enabled)

These fields are required before enabling any `push_*` setting:

| Field | Purpose |
| - | - |
| `company` | The StudioEnterprise company/entity the sync writes under |
| `currency` | Currency code used on pushed transactions |
| `default_source` | Default Source Code (campaign) applied when a gift has no matching campaign |
| `default_project` | Default Project (fund) applied when a gift has no matching designation |
| `recurring_category` | Category applied to recurring plans pushed to StudioEnterprise |

## Contact Type Mapping

StudioEnterprise requires every stored email, phone number, and address to
carry a defined "type" code (for example, "Home" or "Business"). WeGive
stores a fixed set of contact fields per donor; each one maps to a
configurable StudioEnterprise type code. **A contact field with no type
configured is simply not sent** — it does not cause a sync error.

<AccordionGroup>
  <Accordion title="Email type mapping">
    `email_1_type`, `email_2_type`, `email_3_type` — WeGive supports up to
    three email addresses per donor, each independently mapped.
  </Accordion>

  <Accordion title="Phone type mapping">
    `mobile_phone_type`, `office_phone_type`, `home_phone_type`,
    `other_phone_type` — WeGive's four phone fields, each independently
    mapped. Phone numbers are normalized to digits-only (a 10-digit US number)
    before being sent, regardless of how they're formatted in WeGive.
  </Accordion>

  <Accordion title="Address type mapping">
    `address_mailing_type`, `address_billing_type` — a donor's mailing address
    is sent as the account's primary address; a configured billing address is
    added as a secondary address on the account.
  </Accordion>
</AccordionGroup>

## Recurring Giving Configuration

### Frequency Mapping

`frequency_map` · *object* · optional override

WeGive translates StudioEnterprise's recurring-frequency codes to WeGive's
own frequency values using a built-in default mapping (monthly, weekly,
quarterly, bi-weekly, semi-monthly, annually). Your organization can override
any code's mapping — including mapping a code to "excluded" so those plans
are not imported.

<Note>
  StudioEnterprise's "One-Time" frequency code is not a recurring cadence and
  is excluded from recurring-plan import by default.
</Note>

### Recurring Status Mapping

`recurring_status_map` · *object* · optional override

WeGive translates StudioEnterprise's recurring-plan status codes to one of
three WeGive plan states — **active**, **paused**, or **cancelled** — using
a built-in default mapping. Your organization can override this per code.

<Note>
  A single failed charge attempt or a validation error on a recurring plan
  does **not** mark the plan as cancelled by default — only an explicit hold
  status maps to paused. A truly cancelled plan is detected differently (via
  StudioEnterprise's change-tracking, not a status code) and is not imported
  as an active plan.
</Note>

## Fulfillment / Premium Configuration (optional)

`fulfillment_config` · *object* · optional

If your organization sends physical thank-you gifts ("premiums") alongside
certain donations, this optional configuration lets WeGive attach a
fulfillment order to a pushed gift at the same time it's created — this
can't be added to a gift after the fact in StudioEnterprise. Requires a
custom field mapping, warehouse, shipping method, and pricing configuration
from your StudioEnterprise setup; contact WeGive support to configure this.

## Sync Timing

* **Pull frequency**: configurable, default every 15 minutes
* **Incremental sync**: after the first full historical import, ongoing
  pulls only process records that changed since the last sync — not a full
  rescan
* **Push timing**: transactions and donor updates push as they occur in
  WeGive, subject to each toggle being enabled

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Mapping Guide" href="/external/onboarding/donordirect/data-mapping/overview">
    Learn how data is mapped between WeGive and StudioEnterprise
  </Card>

  <Card title="Integration Nuances" href="/external/onboarding/donordirect/integration-nuances">
    Understand platform-specific behaviors and current limitations
  </Card>
</CardGroup>

## Support

Need help with configuration? Contact our support team at
[support@wegive.com](mailto:support@wegive.com).


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