> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Gifts
> The Gift resource in Raise — the donation submission path through /api/Raise/give, the read-and-refund endpoint set, and the relationships to Donors, Projects, and recurring schedules.
A Gift in Raise is a single completed donation. It carries the donation amount, payment processor result, status, project allocations, optional premium and tribute, and references to the donor and (if applicable) the recurring gift schedule that produced it.
The most distinctive aspect of the Gift resource: **Gifts are not created via `POST /api/Gift`**. The Gift POST and PUT endpoints don't exist. Donations enter Raise exclusively through the `POST /api/Raise/give` donation submission path, which processes payment and then creates the Gift record. This page covers both the resource shape and the unique creation flow.
## The Gift record
The Gift record has 56 fields covering identity, payment, designation, status, and a number of optional attribution and analytics fields. The most important groups:
### Identity and amount
| Field | Type | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------ |
| `id` | integer | The Raise primary key. Immutable after creation. |
| `amount` | number | The gift amount. |
| `currency` | string | The currency code (e.g., `"USD"`). |
| `formattedAmount` | string | The amount pre-formatted for display in the donor's currency. |
| `date` | string | The gift date in the donor's local timezone. |
| `createdDate` | string | When the Gift record was created (typically equals `date` for live donations). |
| `modifiedDate` | string | When any field on the record was last changed. |
### Status and capability
| Field | Type | Description |
| ------------- | ------------ | ---------------------------------------------------------- |
| `status` | integer enum | The Gift's processing status. |
| `statusText` | string | The display string for the status. |
| `canRefund` | boolean | `true` if the Gift is eligible for refund through the API. |
| `isAnonymous` | boolean | `true` if the donor opted to give anonymously. |
| `isTestMode` | boolean | `true` if the Gift was created in test mode. |
`status` is an integer enum, but the Raise OpenAPI spec doesn't document the mapping of integer values to status labels. Use `statusText` for display purposes; for programmatic logic, discover the status enum's meanings against the live API and store the mapping in your integration.
**⚠️ Spec gap:** Gift status enum values are not documented in the spec. Future spec updates are expected to label these. Until then, partners should rely on `statusText` and not switch on the integer `status` directly.
### Payment details
| Field | Type | Description |
| ------------------------------- | ------ | ------------------------------------------------------------------------- |
| `gateway` | string | Internal display name of the payment gateway used. |
| `paymentType` | string | The payment method type (credit card, ACH, etc.). |
| `paymentInfo` | string | Display string with payment method details (e.g., "Visa ending in 4242"). |
| `transactionId` | string | The payment processor's transaction reference. |
| `authorizationNumber` | string | The gateway authorization number. |
| `donationId` | string | An additional donation-flow identifier. |
| `paymentProviderTransactionUrl` | string | A URL to view the transaction in the payment processor's UI. |
### Designation
| Field | Type | Description |
| ------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `projects` | array of `GiftProjectAllocationModel` | The breakdown of the Gift across Projects. Each entry specifies a Project and the amount allocated to it. |
| `premiumItem` | `GiftPremiumItem` | The single premium item the donor received in exchange (if any). Note: one premium per gift, unlike some donation platforms that allow multiple. |
For a single-Project gift, `projects[]` has one entry for the full amount. For a split gift, multiple entries summing to the gift's `amount`.
### Donor linkage
| Field | Type | Description |
| ----------------- | ------------------- | ------------------------------------------------------ |
| `donorId` | integer | The ID of the Donor this Gift belongs to. |
| `donor` | `DonorModel` | Embedded donor data (when included in the response). |
| `billingName` | string | The name on the billing payment method. |
| `billingAddress` | `DonorAddressModel` | The billing address used for the payment. |
| `shippingAddress` | `DonorAddressModel` | The shipping address (used when a premium is shipped). |
| `shippingName` | string | The name for shipping. |
### Recurring linkage
| Field | Type | Description |
| ----------------------- | ------- | -------------------------------------------------------------------------- |
| `recurringGiftId` | integer | If non-null, the ID of the RecurringGift schedule that produced this Gift. |
| `recurringScheduleInfo` | object | Summary information about the recurring schedule (when applicable). |
A Gift with `recurringGiftId` set is one payment in a recurring schedule. A Gift without it is a one-time donation.
### Tribute
| Field | Type | Description |
| --------- | ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `tribute` | `GiftTributeModel` | Tribute or memorial information — who the gift was given in honor of or memory of. Null for non-tribute gifts. |
### Campaign and segment attribution
| Field | Type | Description |
| ------------------------- | --------------- | -------------------------------------------- |
| `campaignName` | string | The Campaign this Gift is attributed to. |
| `segment` | string | The Segment code. |
| `segmentName` | string | The Segment's display name. |
| `motivation` | string | The motivation code text. |
| `motivationCodeId` | integer | The MotivationCode's ID. |
| `motivationCodeName` | string | The MotivationCode's display name. |
| `motivationCodeGroupId` | integer | The MotivationCodeGroup's ID. |
| `motivationCodeGroupName` | string | The MotivationCodeGroup's display name. |
| `form` | `GiftFormModel` | The Donation Form that originated this Gift. |
### Marketing attribution (UTM and analytics)
| Field | Type | Description |
| ------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------- |
| `googleUtmCampaign`, `googleUtmContent`, `googleUtmMedium`, `googleUtmSource`, `googleUtmTerm`, `googleUtmId` | string | Google UTM tracking parameters captured at the time of donation. |
| `googleGclid` | string | Google Click Identifier — connects a gift back to a specific ad click. |
| `submissionUrl` | string | The URL of the page the donor was on when they submitted. |
| `browserInfo` | object | Browser fingerprint information captured during submission. |
UTM and Google Click ID tracking is useful for closing the loop on paid acquisition campaigns — partners building donation-attribution analytics use these fields to attribute gifts back to the marketing channel that drove them.
### Other fields
| Field | Type | Description |
| -------------------------------------- | -------------- | ---------------------------------------------------------------------------- |
| `notes` | string | Internal notes about the Gift. |
| `comment` | string | Donor-provided comment with the donation. |
| `donorPaidCosts` | boolean | `true` if the donor opted to cover the platform processing fee. |
| `giftAidRequested` | boolean | `true` if the donor requested UK Gift Aid (tax-relief claim). |
| `virtualTerminalId`, `virtualTerminal` | integer/string | If the Gift was entered manually through Raise's Virtual Terminal interface. |
| `currencyExchange` | object | Currency conversion details when the donation crossed currencies. |
***
## Creating a Gift: `POST /api/Raise/give`
This is the most distinctive aspect of the Raise Gift surface. **There is no `POST /api/Gift`.** Every Gift record in Raise originates from a donation submission through `POST /api/Raise/give`.
### Why this design
`POST /api/Raise/give` isn't a plain "create a Gift" endpoint — it's the full donation flow:
1. **Processes the payment** through the configured payment gateway using the tokenized `paymentMethodId`.
2. **Creates or matches the Donor** record from the embedded donor information.
3. **Creates the Gift** record with the payment result.
4. **Fires the webhook** notifying subscribers of the new Gift.
5. **Initiates platform-level sync** to downstream products like CRM+.
Each of these steps is tightly coupled — you can't create a Gift record without payment processing because the gateway response data is part of the record. This is why the spec exposes no general Gift POST.
### The request body
`POST /api/Raise/give` accepts a `DonatePaymentRequest`:
| Field | Required? | Description |
| ------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `amount` | **Yes** | The donation amount. |
| `paymentMethodId` | **Yes** | The tokenized payment method (see [test-payment-method generator](/raise/base-urls#use-the-test-payment-method-generator) for dev). |
| `paymentMethodType` | **Yes** | The payment method type (credit card, ACH, PayPal, etc.). |
| `currency` | No | Currency code. Defaults to the organization's primary currency. |
| `donor` | No | Donor information for matching/creating the donor record. |
| `projects` | No | The designation breakdown. If omitted, the Gift designates to the form's default Project. |
| `isRecurring` | No | `true` to set up a recurring schedule. |
| `frequency` | No | The recurring frequency (when `isRecurring` is `true`). |
| `startDate` / `startDateTimeUtc` | No | When the recurring schedule starts. |
| `segment` / `segmentOverrideCode` | No | The Segment code. |
| `projectOverrideCode` | No | Override the default Project. |
| `premiumId` | No | The Premium the donor selected. |
| `motivationCodeId`, `motivationCodeGroupId` | No | Attribution codes. |
| `gatewayId` | No | Override the payment gateway. |
| `tribute` | No | Tribute information (in honor of, in memory of, etc.). |
| `isAnonymous` | No | `true` if the donor chose to be anonymous. |
| `donorPaidCosts`, `coverAdminFee`, `adminFee`, `adminFeeProjectId` | No | Fee-coverage configuration. |
| `giftAidRequested` | No | UK Gift Aid request flag. |
| `doubleTheDonationCompanyId`, `doubleTheDonationEnteredText` | No | Double the Donation employer-match integration fields. |
| `googleGclid`, UTM fields | No | Marketing attribution. |
| `isTestMode` | No | `true` for test mode submissions. |
| `nonce`, `publicId`, `pageRequestId` | No | Form-flow tracking identifiers. |
| `visitorId`, `sessionId`, `clientId` | No | Browser session identifiers. |
| `timeZone` | No | The donor's timezone. |
| `comments` | No | Donor-supplied comment. |
### A minimal request
```bash cURL theme={null}
curl -X POST https://prod-api.raisedonors.com/api/Raise/give \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 50.00,
"paymentMethodId": "tok_abc123",
"paymentMethodType": "CreditCard",
"donor": {
"firstName": "Bruce",
"lastName": "Wayne",
"email": "bruce@wayne.example"
},
"projects": [
{ "projectCode": "GEN-FUND", "amount": 50.00 }
]
}'
```
The donor-matching algorithm processes the embedded donor block — typically by email — and either creates a new Donor or attaches the Gift to an existing one. See [Process a Donation](/raise/workflows/process-a-donation) for the end-to-end workflow including donor matching detail and error handling.
The `paymentMethodId` must be a tokenized payment method, not a raw card number. Raise uses tokenization to keep partner integrations out of PCI scope. For development and testing, use `POST /api/Raise/generate-test-payment-method` to mint a test token without touching real card data.
***
## Reading Gifts
The Gift resource exposes read endpoints in three patterns:
| Pattern | Endpoint | Use |
| -------------------------- | ---------------------- | ---------------------------------------------------------------------- |
| List all | `GET /api/Gift/list` | Paginated list of all Gifts. Supports the standard `/list` parameters. |
| Query by structured filter | `POST /api/Gift/query` | Advanced filtering via `groups[]`/`conditions[]`. |
| Get by ID | `GET /api/Gift/{id}` | A single Gift with full detail. |
For reading Gifts associated with a specific Donor, prefer the `GET /api/Donor/{donorId}/gifts` endpoint — it's filtered to the donor at the source rather than requiring you to query by `donorId`.
### Custom field values on a Gift
```bash cURL theme={null}
curl https://prod-api.raisedonors.com/api/Gift/9876/gift-fields \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
Returns the custom field responses captured for this Gift — typically values from custom fields on the Donation Form that produced it.
***
## Refunding a Gift
The Gift surface has no `PUT /api/Gift/{id}` for general updates, but it does support refunds via a dedicated endpoint:
```bash cURL theme={null}
curl -X POST https://prod-api.raisedonors.com/api/Gift/9876/refund \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 50.00,
"reason": "Donor requested cancellation"
}'
```
A refund initiates the reverse payment flow with the original gateway, returns the funds to the donor's payment method, and marks the Gift as refunded on the Raise side. The `canRefund` flag on the Gift indicates eligibility — typically `false` for Gifts that have already been refunded, settled past the gateway's refund window, or have other constraints.
Partial refunds (refunding less than the full Gift amount) may be supported depending on the gateway. Confirm with the customer's gateway configuration before relying on partial refund behavior.
***
## Deleting a Gift
```bash cURL theme={null}
curl -X DELETE https://prod-api.raisedonors.com/api/Gift/9876 \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
`DELETE /api/Gift/{id}` removes a Gift record entirely. Use sparingly — deletion erases the gift's history and accounting impact. The refund endpoint is the right choice for most "cancel this donation" scenarios because it preserves the audit trail.
Deletion is most appropriate for:
* Test gifts created during development that need cleanup.
* Genuine data-entry errors caught before any downstream system has acknowledged the gift.
For donations that were successfully processed but need to be reversed, refund instead.
***
## Updating notes on a Gift
Gift notes have a dedicated update endpoint, parallel to the Donor notes pattern:
```bash cURL theme={null}
curl -X PUT https://prod-api.raisedonors.com/api/Gift/9876/notes \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "notes": "Acknowledged via thank-you email on 2025-01-15" }'
```
This is the only field-level update available on a Gift through the API. Other field changes (amount corrections, designation reallocations, gateway adjustments) are not exposed as API operations and must be performed by the customer's staff in the Raise admin UI.
***
## Gift creation paths in practice
To recap the complete creation flow, since this is one of the most-asked questions for partners new to Raise:
| Scenario | Path |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Donor completes a Raise-hosted donation form | The form's submit handler calls `POST /api/Raise/give` |
| Partner integration embeds a donation form on its own site | The integration code calls `POST /api/Raise/give` |
| Recurring schedule processes a scheduled payment | Raise's payment processor creates the Gift automatically — no API call needed from your side |
| Customer's staff manually records a gift | Through the Raise admin UI, not the API |
| Customer imports historical gifts | Through Raise's bulk import tools in the admin UI |
There is no API path for partners to create Gifts that bypass `POST /api/Raise/give`. Integration designs that need "create a Gift record without processing a payment" should route through the customer's admin team using import tools rather than the API.
***
## Where to go next
The end-to-end workflow for submitting a donation via `POST /api/Raise/give`.
The schedule resource that produces Gifts on a regular interval.
The forms that originate most Gifts — their configuration drives the Gift's segment, motivation, and form attribution.
Read Gifts back out for reporting, reconciliation, or sync.