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

# Recurring Donation Data Mapping

> Detailed field mapping for recurring/sustaining giving plans between WeGive and StudioEnterprise

# Recurring Donation Data Mapping

This page covers how WeGive Scheduled Donations map to StudioEnterprise
Recurring Plans.

**StudioEnterprise Object**: Recurring Plan (header + line records)
**Sync Direction**: Bidirectional (pull on by default; push optional, off
by default)

## Core Identity Fields

| WeGive Field | StudioEnterprise Field | Notes |
| - | - | - |
| `donor_direct_id` | Recurring Plan Header ID | Primary correlation key |

## Frequency Mapping

StudioEnterprise's recurring-frequency code maps to WeGive's frequency
values using a built-in default, overridable per organization via the
`frequency_map` [configuration setting](/external/onboarding/donordirect/configuration-options):

| StudioEnterprise Code | Meaning | WeGive Frequency |
| - | - | - |
| `M` | Monthly | Monthly |
| `W` | Weekly | Weekly |
| `Q` | Quarterly | Quarterly |
| `BW` | Bi-Weekly | Every 2 weeks |
| `SM` | Semi-Monthly | 1st & 15th of the month |
| `A` | Annually | Yearly |
| `O` | One-Time | Not imported (not a recurring cadence) |

## Status Mapping

StudioEnterprise's recurring-plan status code maps to one of three WeGive
plan states, using a built-in default, overridable via the
`recurring_status_map` configuration setting:

| StudioEnterprise Code | Meaning | WeGive State |
| - | - | - |
| `Y` | Ready for Processing | Active |
| `H` | Hold Processing | Paused |
| `D` | Decline (a real-time charge attempt failed) | Active (plan continues) |
| `E` | Validation Error | Active (plan continues) |

<Note>
  A declined charge attempt or a validation error does **not** cancel a
  plan by default — the plan stays active and the next scheduled charge is
  still attempted. A genuinely cancelled recurring plan isn't represented by
  a status code in StudioEnterprise; it's detected through StudioEnterprise's
  change-tracking data instead (the plan record itself is removed/ended).
</Note>

## Linking Gifts to Their Recurring Plan

Individual gifts produced by a recurring plan carry a reference back to the
plan's Header ID. This is how WeGive knows a specific transaction was
generated by a specific sustaining/recurring giving plan, rather than being
a standalone one-time gift.

## Pull Behavior

Recurring plan data is read at the line-item grain and folded up per plan
header — a plan's amount is the sum of its designation lines. Because pull
processes records in pages, a single plan whose lines span more than one
page is still correctly totaled across pages, not just from the first page
encountered.

## Push Behavior

When enabled, WeGive pushes recurring plan records to StudioEnterprise as
record-keeping entries — reflecting that the plan exists and its schedule —
rather than instructing StudioEnterprise to process payments on WeGive's
behalf. Payment processing for recurring gifts happens within WeGive.

## Not Yet Supported

<AccordionGroup>
  <Accordion title="Multi-fund recurring plans">
    A recurring plan split across multiple fund designations is not yet
    represented.
  </Accordion>
</AccordionGroup>

## Related Documentation

<CardGroup cols={2}>
  <Card title="Transaction Mapping" href="/external/onboarding/donordirect/data-mapping/transaction">
    See how individual gifts link back to their recurring plan
  </Card>

  <Card title="Configuration Options" href="/external/onboarding/donordirect/configuration-options">
    Configure frequency and status mapping overrides
  </Card>
</CardGroup>

For additional help with recurring donation mapping, 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.