Skip to content

Donation (Giving)

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

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;

Type to search…

↑↓ navigate↵ selectEsc close