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

# RecurringGift Mapping

> How WeGive scheduled donations map to Virtuous recurring gifts, in both directions

# RecurringGift Mapping

WeGive **Scheduled Donations** map to Virtuous **RecurringGift** records.

## Record Model

| WeGive record | Virtuous record | Correlation column |
| - | - | - |
| Scheduled Donation | `RecurringGift` | `virtuous_id` |

## Frequency Mapping

| WeGive frequency | Virtuous `frequency` |
| - | - |
| weekly | `Weekly` |
| monthly | `Monthly` |
| quarterly | `Quarterly` |
| yearly | `Annually` |

## Push (WeGive → Virtuous)

Before pushing, the integration first pushes any related records that lack a `virtuous_id` — the donor (Contact), the campaign (Segment), and the fund(s) (Projects).

### Creating a recurring gift

```
POST RecurringGift
{
  "startDate": <start_date, Y-m-d>,
  "nextExpectedPaymentDate": <see below>,
  "frequency": "Weekly" | "Monthly" | "Quarterly" | "Annually",
  "amount": <charge_amount / 100>,
  "automatedPayments": true,
  "trackPayments": true,
  "isPrivate": <anonymous>,
  "segmentId": <campaign.virtuous_id>,
  "designations": [ { "projectId": <project>, "amountDesignated": <dollars> } ],
  "contactId": <source.virtuous_contact_id>
}
```

The returned `id` is stored as the scheduled donation's `virtuous_id`.

<Note>
  `nextExpectedPaymentDate` isn't simply `start_date` — if the plan's `start_date` is today, in the past, or within the next day, it's bumped forward to 2 days from now instead. This avoids telling Virtuous to expect a payment that's already due or overdue at creation time.
</Note>

### Amount and fees

The pushed `amount` is the **`charge_amount`** (base amount **plus** fees), not the base amount. The `designations` are built so their sum equals `charge_amount`:

* When fee-splitting is on (or no fee fund is configured), the fee is distributed proportionally across the allocation designations, with rounding absorbed by the last row.
* When a dedicated fee fund is configured, the fee is added as (or merged into) a separate designation for that fund.

This mirrors WeGive's own recurring fee allocation so per-installment gifts and the recurring plan stay aligned in Virtuous.

### Updating a recurring gift

When the scheduled donation already has a `virtuous_id`, the integration `GET`s the RecurringGift and overwrites the WeGive-owned fields, then `PUT`s it back:

* `nextExpectedPaymentDate`, `amount`, `isPrivate`, `segmentId`
* `designations` — replaced entirely (WeGive is the source of truth for allocations)

## Pull (Virtuous → WeGive)

RecurringGifts are pulled via `POST RecurringGift/Query` (1000 per page, filtered by the configured `pull_by` date) and imported as Scheduled Donations, matched on `virtuous_id`:

| WeGive field | Source | Notes |
| - | - | - |
| `virtuous_id` | recurring gift `id` | |
| `start_date` | `nextExpectedPaymentDate` | |
| `created_at` | `createDateTimeUtc` | |
| `deleted_at` | `cancelDateTimeUtc` | Set when the gift is cancelled in Virtuous |
| `frequency` | reverse of the frequency map above | |
| `anonymous` | `isPrivate` | |
| `amount` | `amount * 100` | **New records only** |
| `fee_amount` | `0` | **New records only** |

> `amount` and `fee_amount` are set only on first import. On existing records, WeGive is the source of truth — Virtuous stores the fee-inflated `charge_amount`, so pulling it would create a feedback loop of growing fees.

**Source resolution:** a company donor (by `virtuous_contact_id`, no individual) is tried first; otherwise the Contact's primary individual. **Fund** comes from the first designation's `projectId`; **campaign** from `segmentId`. When fund allocations are enabled, allocations are synced to WeGive from the designations **on first import only** (`amountDesignated * 100` → allocation amount).

This reflects the integration as implemented in `app/Integrations/Virtuous.php`.


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