A Donation record corresponds to a gift given to an Organization at a particular point in time.
Donations 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 (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 |
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; 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. |
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_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. |
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_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_method |
string | null |
See details. |
payment_method_sub |
string | null |
See details. |
payment_status |
string | null |
See details. |
received_at |
string | null |
See details. |
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
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
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
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 allows it.
payment_channel
The channel through which the donation was created.
Possible values: api, sms, mobile_app, web, admin, or other
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
Required. The payment method used to make a donation.
Possible values: ach, cash, check, or card
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
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
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 | No |
campus |
To one | Campus | No |
labels |
To many | Labels |
Yes |
payment_source |
To one | PaymentSource | No |
person |
To one | Person | No |
recurring_donation |
To one | RecurringDonation | 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 | Collection | No | |
ref.designations |
Designation | Collection | No | |
ref.labels |
Label | Collection | No | |
ref.note |
Note | Single resource | Yes | |
ref.refund |
Refund | Single resource | No |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on donations on 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.
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
import type { Giving } from '@mackenly/planningcenterkit';
const page = await pco.giving.donations.order('completed_at').perPage(25).list();
const items: Giving.Donation[] = page.data;