API
⌘K
My Developer Account

Donation

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.

Example Request

curl https://api.planningcenteronline.com/giving/v2/donations

View in API Explorer →

Example Object

{
  "type": "Donation",
  "id": "1",
  "attributes": {
    "amount_cents": 1,
    "amount_currency": "USD",
    "completed_at": "2000-01-01T12:00:00Z",
    "created_at": "2000-01-01T12:00:00Z",
    "fee_cents": 1,
    "fee_covered": true,
    "fee_currency": "USD",
    "memo": "string",
    "payment_brand": "string",
    "payment_channel": "string",
    "payment_check_dated_at": "2000-01-01",
    "payment_check_number": 1,
    "payment_last4": "string",
    "payment_method": "value",
    "payment_method_sub": "value",
    "payment_status": "value",
    "received_at": "2000-01-01T12:00:00Z",
    "refundable": true,
    "refunded": true,
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "batch": {
      "data": {
        "type": "Batch",
        "id": "1"
      }
    },
    "campus": {
      "data": {
        "type": "Campus",
        "id": "1"
      }
    },
    "person": {
      "data": {
        "type": "Person",
        "id": "1"
      }
    },
    "payment_source": {
      "data": {
        "type": "PaymentSource",
        "id": "1"
      }
    },
    "labels": {
      "data": [
        {
          "type": "Labels",
          "id": "1"
        }
      ]
    },
    "recurring_donation": {
      "data": {
        "type": "RecurringDonation",
        "id": "1"
      }
    }
  }
}

Attributes

Name Type Description
amount_cents integer The number of cents being donated. Derived from the total of all of a donation's associated designation's `amount_cents` values.
amount_currency currency_abbreviation The currency of `amount_cents`. Based on the organization's currency.
completed_at date_time 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`
created_at date_time The date and time at which a donation was created. Example: `2000-01-01T12:00:00Z`
fee_cents integer 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.
fee_covered boolean 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 currency_abbreviation The currency of `fee_cents`. Based on the organization's currency.
id primary_key The unique identifier for a donation.
memo string 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.
payment_brand string 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 The channel through which the donation was created. Possible values: `api`, `sms`, `mobile_app`, `web`, `admin`, or `other`
payment_check_dated_at date The check date for donations made by check. Example: `2000-01-01`
payment_check_number integer The check number for donations made by check.
payment_last4 string 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 string Required. The payment method used to make a donation. Possible values: `ach`, `cash`, `check`, or `card`
payment_method_sub string 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 string 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 date_time 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`
refundable boolean 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 Returns `true` if a donation has been refunded, or `false` if it hasn't.
updated_at date_time The date and time at which a donation was last updated. Example: `2000-01-01T12:00:00Z`

Relationships

Name Type Association Type Note
batch Batch to_one
campus Campus to_one `Campus` is automatically assigned based on the donor's primary campus. If you pass an explicit value (a relationship reference or `null`), it will override the default.
person Person to_one `Person` is _not_ required. If it is not present, the donation will show up in the web interface as having an "Anonymous Donor," and the `person` relationship in the API will be `null`.
payment_source PaymentSource to_one `PaymentSource` is required, but cannot be `planning_center`, as that is reserved for Donations created in the Planning Center Giving Web UI.
labels Labels to_many
recurring_donation RecurringDonation to_one

Can Include

Parameter Value Description Assignable
include designations include associated designations create and update
include labels include associated labels create and update
include note include associated note
include refund include associated refund

Order By

Parameter Value Type Description
order completed_at string prefix with a hyphen (-completed_at) to reverse the order
order created_at string prefix with a hyphen (-created_at) to reverse the order
order received_at string prefix with a hyphen (-received_at) to reverse the order
order updated_at string prefix with a hyphen (-updated_at) to reverse the order

Query By

Name Parameter Type Description Example
completed_at where[completed_at] date_time Query on a specific completed_at ?where[completed_at]=2000-01-01T12:00:00Z
created_at where[created_at] date_time Query on a specific created_at ?where[created_at]=2000-01-01T12:00:00Z
payment_method where[payment_method] string Query on a specific payment_method Possible values: `ach`, `cash`, `check`, or `card` ?where[payment_method]=value
received_at where[received_at] date_time Query on a specific received_at ?where[received_at]=2000-01-01T12:00:00Z
updated_at where[updated_at] date_time Query on a specific updated_at ?where[updated_at]=2000-01-01T12:00:00Z

Pagination

Name Parameter Type Description
per_page per_page integer how many records to return per page (min=1, max=100, default=25)
offset offset integer get results from given offset

Endpoints

Listing

HTTP Method Endpoint
GET /giving/v2/donations

Reading

HTTP Method Endpoint
GET /giving/v2/donations/{id}

Creating

HTTP Method Endpoint Assignable Attributes
POST /giving/v2/batches/{batch_id}/donations
  • payment_method_sub
  • payment_last4
  • payment_brand
  • payment_check_number
  • payment_check_dated_at
  • fee_cents
  • payment_method
  • received_at
  • person_id
  • payment_source_id
  • campus_id

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /giving/v2/donations/{id}
  • payment_method_sub
  • payment_last4
  • payment_brand
  • payment_check_number
  • payment_check_dated_at
  • fee_cents
  • payment_method
  • received_at
  • person_id
  • payment_source_id
  • campus_id

Deleting

HTTP Method Endpoint
DELETE /giving/v2/donations/{id}

Actions

HTTP Method Endpoint Description
POST https://api.planningcenteronline.com/giving/v2/donations/{donation_id}/issue_refund Used to refund a batch donation

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/giving/v2/donations/{donation_id}/campus Campus
GET https://api.planningcenteronline.com/giving/v2/donations/{donation_id}/designations Designation
GET https://api.planningcenteronline.com/giving/v2/donations/{donation_id}/labels Label
GET https://api.planningcenteronline.com/giving/v2/donations/{donation_id}/note Note
GET https://api.planningcenteronline.com/giving/v2/donations/{donation_id}/refund Refund

Belongs To

HTTP Method Endpoint Association Details Filter By
GET https://api.planningcenteronline.com/giving/v2/batches/{batch_id}/donations Batch
GET https://api.planningcenteronline.com/giving/v2/campuses/{campus_id}/donations Campus
GET https://api.planningcenteronline.com/giving/v2/donations Organization
  • succeeded
GET https://api.planningcenteronline.com/giving/v2/payment_sources/{payment_source_id}/donations PaymentSource
GET https://api.planningcenteronline.com/giving/v2/people/{person_id}/donations Person