---
title: "Donation (Giving)"
description: "A Donation record corresponds to a gift given to an Organization at a particular point in time."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Donation (Giving)

A `Donation` record corresponds to a gift given to an `Organization` at a particular point in time.

`Donation`s are added by first associating them to a `Batch` of donations, and then committing the `Batch`. When adding a `Donation` to an already-committed `Batch`, the `Donation` will automatically be committed as well, and immediately added to the donor's online history.

**Totals**

On donation collection endpoints, pass `?with_totals=true` to add the received total to the response `meta`. It respects any `where[...]` filters and is unaffected by pagination. Totals are not available when filtering by `fund_id`.

- `received_total_amount_cents`: the total received, excluding refunded and failed donations.
- `currency`: the currency of the totals above, based on the organization's currency.

| Property | Value |
| --- | --- |
| Product | [Giving](/reference/giving/) (`pco.giving`, API version `2019-10-18`) |
| Resource type | `Donation` |
| TypeScript | `Giving.Donation`, attributes `Giving.DonationAttributes`, schema `Giving.DonationSchema` |
| Planning Center path | `/giving/v2/donations` |
| Planning Center docs | [Donation](https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/donation) |

## How to reach it

| Client path | Returns | Filters | Create |
| --- | --- | --- | --- |
| `pco.giving.donations` | Collection | `succeeded` | No |
| `pco.giving.batches.id(batchId).donations` | Collection |  | Yes |
| `pco.giving.campuses.id(campusId).donations` | Collection |  | No |
| `pco.giving.payment_sources.id(paymentSourceId).donations` | Collection |  | No |
| `pco.giving.people.id(personId).donations` | Collection |  | No |

From a collection, `.id(donationId)` addresses one Donation: `pco.giving.donations.id(donationId)`. Collections support [`where`, `include`, `order`, and pagination](/guides/querying/); single resources have `get()`.

## Attributes

On `Giving.DonationAttributes`. Every resource also has `id` and `type` (`'Donation'`) next to its attributes.

| Name | Type | Description |
| --- | --- | --- |
| `amount_cents` | `number \| null` | The number of cents being donated. Derived from the total of all of a donation's associated designation's `amount_cents` values. |
| `amount_currency` | `string \| null` | The currency of `amount_cents`. Based on the organization's currency. |
| `completed_at` | `string \| null` | See [details](#completed-at). |
| `created_at` | `string \| null` | The date and time at which a donation was created. Example: `2000-01-01T12:00:00Z` |
| `fee_cents` | `number \| null` | See [details](#fee-cents). |
| `fee_covered` | `boolean \| null` | A boolean indicating whether the donor chose to cover the Stripe processing fee for this donation.Note that `fee_covered` can only be true for donations processed through Stripe. |
| `fee_currency` | `string \| null` | The currency of `fee_cents`. Based on the organization's currency. |
| `memo` | `string \| null` | See [details](#memo). |
| `payment_brand` | `string \| null` | For cards, this is the card brand (eg Visa, Mastercard, etc). For checks and bank accounts, this is the bank name. For cash donations, this should be `null`. |
| `payment_channel` | `string \| null` | See [details](#payment-channel). |
| `payment_check_dated_at` | `string \| null` | The check date for donations made by check. Example: `2000-01-01` |
| `payment_check_number` | `number \| null` | The check number for donations made by check. |
| `payment_last4` | `string \| null` | See [details](#payment-last4). |
| `payment_method` | `string \| null` | See [details](#payment-method). |
| `payment_method_sub` | `string \| null` | See [details](#payment-method-sub). |
| `payment_status` | `string \| null` | See [details](#payment-status). |
| `received_at` | `string \| null` | See [details](#received-at). |
| `refundable` | `boolean \| null` | A boolean indicating whether this donation can be refunded via the API. Note that for some donations, this may be false, even though the donation _can_ be refunded in the UI. |
| `refunded` | `boolean \| null` | Returns `true` if a donation has been refunded, or `false` if it hasn't. |
| `updated_at` | `string \| null` | The date and time at which a donation was last updated. Example: `2000-01-01T12:00:00Z` |

### Attribute details

#### `completed_at` {#completed-at}

The date and time at which a donation was completely processed. For card and ACH donations processed by Stripe, this is the moment when the donation was marked as fully processed by Stripe. For committed batch donations, this is the moment that the batch was committed. For uncommitted batch donations, this should return `null`. Example: `2000-01-01T12:00:00Z`

#### `fee_cents` {#fee-cents}

The fee to process a donation. This should either be 0 or a negative integer. For a donation processed by Giving via Stripe, this is the amount the associated organization paid Stripe to process it. For donations not processed by Stripe, this can be used to record fees from other systems. Note: while `amount_cents` is assigned via a donation's designations, `fee_cents` is set here, and used by Giving to distribute fees across all designations in proportion to the amount of each designation.

#### `memo` {#memo}

An optional short note donors can add to specify their gift intention (e.g. "In memory of..."). Only available when enabled by the church for specific funds. Can be set on batch donations when the [memo line feature](https://help.planningcenter.com/en/143011-manage-your-online-donation-form.html#UUID-0949cfc8-d262-e23a-0635-fa100ae331ba_section-id235309330415896-how-do-memo-lines-work-) allows it.

#### `payment_channel` {#payment-channel}

The channel through which the donation was created.

 Possible values: `api`, `sms`, `mobile_app`, `web`, `admin`, or `other`

#### `payment_last4` {#payment-last4}

The last 4 digits of a donation's payment method number. For cards, this is the last 4 digits of the card number. For bank accounts, this is the last 4 digits of the bank account number. For cash and check donations, this should be `null`. Note: In cases where we don't have all 4 digits on file, a `*` will be used to pad the number. For example: `*321`

#### `payment_method` {#payment-method}

Required. The payment method used to make a donation.

Possible values: `ach`, `cash`, `check`, or `card`

#### `payment_method_sub` {#payment-method-sub}

For cards, this will be the card subtype. Will be `null` for other payment method types.

Possible values: `credit`, `debit`, `prepaid`, or `unknown`

#### `payment_status` {#payment-status}

For Stripe donations, this is the payment status. For batch donations, `pending` means that the donation has not yet been committed, whereas `succeeded` refers to a committed donation.

Possible values: `pending`, `succeeded`, or `failed`

#### `received_at` {#received-at}

The date and time at which a donation was received. For card and ACH donations processed by Stripe, this is the moment when the donation was created in Giving. For batch donations, this is a customizable value that can be set via the Giving UI or API to any date. This allows for batch donations recieved on a previous day to be dated in the past, as well as for postdated checks to have a date in the future. It is important to ensure that this attribute is set accurately, as this is the date used to filter donations in the Giving admin UI. When creating new donations via the API, this attribute will default to the current date and time. Example: `2000-01-01T12:00:00Z`

## Relationships and includes

Side-load with `include()` (or `get({ include })`) and read with `related(resource, name)`: `designations`, `labels`, `note`, `refund`.

| Relationship | Type | To | Includable |
| --- | --- | --- | --- |
| `batch` | To one | [Batch](/reference/giving/batch/) | No |
| `campus` | To one | [Campus](/reference/giving/campus/) | No |
| `labels` | To many | `Labels` | Yes |
| `payment_source` | To one | [PaymentSource](/reference/giving/payment-source/) | No |
| `person` | To one | [Person](/reference/giving/person/) | No |
| `recurring_donation` | To one | [RecurringDonation](/reference/giving/recurring-donation/) | No |

## Querying

### Where

`where(field, value)` for equality; `where(field, op, value)` with the operators listed.

| Field | Value type | Operators |
| --- | --- | --- |
| `completed_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |
| `created_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |
| `payment_method` | `string` | Equality only |
| `received_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |
| `updated_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |

### Order

`order(...)` accepts these fields, ascending, or descending with a `-` prefix: `completed_at`, `created_at`, `received_at`, `updated_at`.

### Filters

`filter(...)` names depend on the edge you query through:

| Edge | Filters |
| --- | --- |
| `pco.giving.donations` | `succeeded` |

## Edges

Follow these from one Donation, `ref = pco.giving.donations.id(donationId)`:

| Edge | Leads to | Returns | Filters | Create |
| --- | --- | --- | --- | --- |
| `ref.campus` | [Campus](/reference/giving/campus/) | Collection |  | No |
| `ref.designations` | [Designation](/reference/giving/designation/) | Collection |  | No |
| `ref.labels` | [Label](/reference/giving/label/) | Collection |  | No |
| `ref.note` | [Note](/reference/giving/note/) | Single resource |  | Yes |
| `ref.refund` | [Refund](/reference/giving/refund/) | Single resource |  | No |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `donations` on [Batch](/reference/giving/batch/) |
| Update | Yes, `update()` on a reference |
| Delete | Yes, `delete()` on a reference |

### Create attributes

Typed as `Giving.DonationSchema['create']`.

| Attribute | Type |
| --- | --- |
| `batch_id` | `string` |
| `campus_id` | `string` |
| `fee_cents` | `number \| null` |
| `labels_ids` | `string[]` |
| `memo` | `string \| null` |
| `payment_brand` | `string \| null` |
| `payment_check_dated_at` | `string \| null` |
| `payment_check_number` | `number \| null` |
| `payment_last4` | `string \| null` |
| `payment_method` | `string \| null` |
| `payment_method_sub` | `string \| null` |
| `payment_source_id` | `string` |
| `person_id` | `string` |
| `received_at` | `string \| null` |

### Update attributes

Typed as `Giving.DonationSchema['update']`.

| Attribute | Type |
| --- | --- |
| `batch_id` | `string` |
| `campus_id` | `string` |
| `fee_cents` | `number \| null` |
| `labels_ids` | `string[]` |
| `memo` | `string \| null` |
| `payment_brand` | `string \| null` |
| `payment_check_dated_at` | `string \| null` |
| `payment_check_number` | `number \| null` |
| `payment_last4` | `string \| null` |
| `payment_method` | `string \| null` |
| `payment_method_sub` | `string \| null` |
| `payment_source_id` | `string` |
| `person_id` | `string` |
| `received_at` | `string \| null` |

See [Writing data](/guides/writing-data/).

## Actions

Run with `ref.action(name, body?)`. Bodies are untyped: see Planning Center's docs for each action.

| Action | Path | Description |
| --- | --- | --- |
| `issue_refund` | `POST /giving/v2/donations/{donation_id}/issue_refund` | Used to refund a batch donation |
| `mark_failed` | `POST /giving/v2/donations/{donation_id}/mark_failed` | Used to mark a donation as failed |

## Example

```ts
import type { Giving } from '@mackenly/planningcenterkit';

const page = await pco.giving.donations.order('completed_at').perPage(25).list();
const items: Giving.Donation[] = page.data;
```

Source: https://planningcenterkit.mackenly.com/reference/giving/donation/index.mdx
