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

# Integration Nuances

> Understand platform-specific behaviors, limitations, and design decisions for the DonorDirect integration

# DonorDirect Integration Nuances

Understanding the specific behaviors and current limitations of the
DonorDirect integration will help you plan your setup and know what to
expect. This page covers why the integration is built the way it is, and
what's still in progress.

<Warning>
  **This integration is under active development.** Several behaviors
  described below as "not yet supported" or "in progress" are known,
  tracked gaps — not oversights. This page will be kept current as those are
  resolved.
</Warning>

## Why This Integration Works Differently From WeGive's Other CRM Integrations

### The Scale Problem

StudioEnterprise's standard API is built to look up one account at a time —
it doesn't offer bulk, date-filtered queries. For an organization with a
large constituent base, a full synchronization through the standard API
alone would require millions of individual API calls, with no reliable way
to detect what changed since the last sync.

### WeGive's Solution: Custom Read-Only Data Endpoints

To make sync practical at scale, WeGive builds and hosts a small set of
custom, read-only data endpoints directly against your StudioEnterprise
environment (using StudioEnterprise's own API extensibility feature). These
endpoints:

* Return account, gift, recurring-plan, fund, and campaign data in efficient,
  paged batches instead of one record at a time
* Include a reliable, timestamp-based change feed, so ongoing syncs only
  process records that actually changed
* Expose relationship data (which gift belongs to which recurring plan,
  which campaign a gift is attributed to) that the standard API doesn't
  surface directly

**Push (WeGive → StudioEnterprise) works differently.** Because these custom
endpoints are read-only, any data WeGive sends back to StudioEnterprise —
new donors, gifts, or recurring plans — goes through StudioEnterprise's
standard write API instead.

<Note>
  This design means initial setup involves WeGive's implementation team
  working directly with your StudioEnterprise environment to build these
  endpoints, rather than a fully self-serve API-key connection. See [Setup
  Requirements](/external/onboarding/donordirect/setup-requirements) for what
  that process looks like.
</Note>

## Synchronization Behaviors

### Full Backfill, Then Incremental

The first sync performs a complete historical import. After that, sync
switches to incremental mode — pulling only records that changed since the
last successful sync, using StudioEnterprise's own change-tracking data
rather than rescanning your full account/gift history each cycle.

### Gifts Are Treated as Immutable Once Synced

Once a gift has been pushed to StudioEnterprise and recorded there, WeGive
does not attempt to update that record on a later sync — gift records are
treated as settled and unchanging. If a gift is refunded in WeGive after
being pushed, the refund is sent as its own follow-up sync rather than
modifying the original record.

### Pushed Gifts Are Recorded as Already-Processed

When WeGive pushes a transaction to StudioEnterprise, it's recorded as an
already-completed gift — StudioEnterprise is not asked to process a new
charge. Actual payment processing happens within WeGive; StudioEnterprise
receives the record for reporting and donor-history purposes.

## Known Current Limitations

<AccordionGroup>
  <Accordion title="Transaction status semantics are still being finalized">
    StudioEnterprise's own gift-status field is coarse, and the precise
    definition of "completed" for import purposes (versus other in-progress or
    reversed states) is still being confirmed as part of this integration's
    rollout. This page will be updated once that mapping is finalized.
  </Accordion>

  <Accordion title="Split-tender payments are not yet supported">
    A single gift paid across multiple payment methods (for example, part
    credit card, part check) is not yet represented on import — the primary
    payment method is used. Support for this is planned for a future phase.
  </Accordion>

  <Accordion title="Deleted-record detection has a known gap">
    StudioEnterprise's change-tracking data ties a deletion event to the
    record's internal ID — but if that record no longer exists in
    StudioEnterprise by the time WeGive processes the deletion event, WeGive
    currently cannot resolve which record it referred to, and the deletion may
    not propagate. A more complete fix (tracking the internal ID at initial
    pull time so it's still available later) is planned.
  </Accordion>

  <Accordion title="Some contact fields are deferred">
    Splitting a donor's email addresses and phone numbers out to StudioEnterprise's
    own typed contact-method records (rather than WeGive's primary email/phone
    slots), and do-not-contact preference sync, are planned for a later phase of
    this integration.
  </Accordion>

  <Accordion title="Multi-fund gifts (fund allocations) are not yet supported">
    A single gift split across more than one fund designation is not yet
    represented in the DonorDirect sync.
  </Accordion>

  <Accordion title="Projects (funds) are one level deep">
    StudioEnterprise supports sub-accounts under a Project; the current
    integration syncs at the Project level only, not the sub-account level.
  </Accordion>

  <Accordion title="Historical campaign hierarchy is simplified">
    Campaign/Source Code attribution is synced using the current campaign
    hierarchy. Year-specific historical changes to that hierarchy over time are
    not yet reflected.
  </Accordion>
</AccordionGroup>

## Data Format Notes

### Currency and Amounts

WeGive stores monetary amounts in cents; StudioEnterprise uses decimal
dollar amounts. Conversion is automatic in both directions.

### Phone Numbers

StudioEnterprise expects a digits-only phone number, up to 10 digits.
WeGive automatically strips formatting and a leading US country code (`1`)
before sending.

### Addresses

StudioEnterprise requires only a country code to accept an address record.
If a donor has no address on file in WeGive, a default country is sent
rather than omitting the address entirely.

## Best Practices

<CardGroup cols={2}>
  <Card title="Coordinate Setup Early" icon="calendar">
    Because setup involves a joint access/configuration process, start
    coordination with WeGive's implementation team well before your target
    go-live date.
  </Card>

  <Card title="Review Contact Type Codes" icon="address-card">
    Confirm your StudioEnterprise contact-type codes (email/phone/address)
    before configuration, so contact information maps correctly from the start.
  </Card>

  <Card title="Plan for Default Fund/Campaign" icon="folder">
    Decide on a default Project and Source Code for gifts that don't map to a
    specific designation, before enabling push.
  </Card>

  <Card title="Start With Pull Only" icon="arrow-down">
    Consider enabling pull first and validating imported data before turning on
    any push direction, since push toggles default off individually per data
    type.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Data Mapping Reference" href="/external/onboarding/donordirect/data-mapping/overview">
    Detailed field mapping documentation
  </Card>

  <Card title="Get Support" href="mailto:support@wegive.com">
    Contact our team for integration assistance
  </Card>
</CardGroup>

For additional questions about specific behaviors, 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.