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

Notes:

A full json example of creating a Donation

{
  "data": {
    "type": "Donation",
    "attributes": {
      "payment_method": "cash",
      "received_at": "2017-10-10"
    },
    "relationships": {
      "person": {
        "data": { "type": "Person", "id": "123" }
      },
      "payment_source": {
        "data": { "type": "PaymentSource", "id": "123" }
      },
      "labels": {
        "data": [
          { "type": "Label", "id": "123" }
        ]
      }
    }
  },
  "included": [
    {
      "type": "Designation",
      "attributes": { "amount_cents": 2000 },
      "relationships": {
        "fund": {
          "data": { "type": "Fund", "id": "123" }
        }
      }
    }
  ]
}

When creating a Donation, you must include at least one Designation, and each Designation must have amount_cents and a Fund relationship

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

Notes:

Designations

When updating a Donation, if you specify an id attribute for each Designation, those Designations can be updated.

However, if you have Designations in the included array without ids, all Designations will be removed and replaced with the Designations in your PATCH request.

Labels

Passing a labels key in the relationships object will have the effect of replacing any existing associated Labels with those in the request. Including a null or empty {} value will remove all Label relationships, but omitting the labels key altogether will leave existing relationships in tact.

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