PcoGivingDonation class

This class represents a PCO Giving Donation Object

Instantiation

  • Create a new instance using the PcoGivingDonation() constructor
  • Instantiate from existing JSON data using the PcoGivingDonation.fromJson() constructor.
  • Load an instance from the API using one of the static methods defined on this class.

Usage

  • Fields exposed by the API are readable through getter methods.
  • Fields writable by the API are exposed through setter methods.
  • Original json data is exposed through the read-only attributes map.
  • Additional data is available through the read-only links and relationships maps.
  • Available relationships / includes are exposed through typed getters.

Extra Instructions

CREATING

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

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.

Description

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.

Attributes (and permissions)

  • id (ro) -> PCO: id
  • createdAt (ro) -> PCO: created_at
  • updatedAt (ro) -> PCO: updated_at
  • paymentMethodSub (rw) -> PCO: payment_method_sub
  • paymentLast4 (rw) -> PCO: payment_last4
  • paymentBrand (rw) -> PCO: payment_brand
  • paymentCheckNumber (rw) -> PCO: payment_check_number
  • paymentCheckDatedAt (rw) -> PCO: payment_check_dated_at
  • feeCents (rw) -> PCO: fee_cents
  • paymentMethod (rw) -> PCO: payment_method
  • receivedAt (rw) -> PCO: received_at
  • amountCents (ro) -> PCO: amount_cents
  • paymentStatus (ro) -> PCO: payment_status
  • completedAt (ro) -> PCO: completed_at
  • amountCurrency (ro) -> PCO: amount_currency
  • feeCurrency (ro) -> PCO: fee_currency
  • isRefunded (ro) -> PCO: refunded
  • isRefundable (ro) -> PCO: refundable
  • personId (wo) -> PCO: person_id
  • paymentSourceId (wo) -> PCO: payment_source_id
  • campusId (wo) -> PCO: campus_id

Edges and Actions

Outbound Edges:

Inbound Edges:

Actions:

Raw Data Object Example

{
  "type": "Donation",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "updated_at": "2000-01-01T12:00:00Z",
    "payment_method_sub": "value",
    "payment_last4": "string",
    "payment_brand": "string",
    "payment_check_number": 1,
    "payment_check_dated_at": "2000-01-01",
    "fee_cents": 1,
    "payment_method": "value",
    "received_at": "2000-01-01T12:00:00Z",
    "amount_cents": 1,
    "payment_status": "value",
    "completed_at": "2000-01-01T12:00:00Z",
    "amount_currency": "USD",
    "fee_currency": "USD",
    "refunded": true,
    "refundable": true
  },
  "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"
      }
    }
  }
}
Inheritance
Available Extensions

Constructors

PcoGivingDonation({required String batchId, String? id, DateTime? createdAt, DateTime? updatedAt, String? paymentMethodSub, String? paymentLast4, String? paymentBrand, int? paymentCheckNumber, String? paymentCheckDatedAt, int? feeCents, String? paymentMethod, DateTime? receivedAt, int? amountCents, String? paymentStatus, DateTime? completedAt, String? amountCurrency, String? feeCurrency, bool? isRefunded, bool? isRefundable, String? personId, String? paymentSourceId, String? campusId, Map<String, List<PcoResource>>? withRelationships, List<PcoResource>? withIncluded})
Create a new PcoGivingDonation object using this endpoint: https://api.planningcenteronline.com/giving/v2/batches/$batchId/donations
factory
PcoGivingDonation.empty()
Create an empty instance of this class. This is only useful when an endpoint requires related or included data.
PcoGivingDonation.fromJson(Map<String, dynamic> data, {List<Map<String, dynamic>>? withIncluded})

Properties

amountCents → int
no setter
amountCurrency → String
no setter
api → PlanningCenter
planning center resources must be tied to an api
no setterinherited
apiEndpoint → String
no setterinherited
apiPath → String
PcoResources include their own path as a link object but this might be null if we haven't created/fetched the object yet Child classes should redefine this getter to allow for manual path overrides
no setteroverride
apiVersion → String
child classes can override these getters which will allow methods in this class to see static variables from child classes
no setteroverride
attributes → ReadOnlyMapView<String, dynamic>
contains the underlying attributes returned by the api and allows a user to access arbitrary data in the attributes by actual api name
no setterinherited
campusId ↔ String
pass null to remove key from attributes
getter/setter pair
canCreate → bool
no setteroverride
canDestroy → bool
no setteroverride
canUpdate → bool
no setteroverride
completedAt → DateTime
no setter
createAllowed → List<String>
no setteroverride
createdAt → DateTime
no setterinherited
createPathTemplate → String
no setteroverride
defaultPathTemplate → String
no setteroverride
feeCents ↔ int
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.
getter/setter pair
feeCurrency → String
no setter
fetched ↔ bool
indicate whether an item is full or partial
getter/setter pairinherited
hashCode → int
The hash code for this object.
no setterinherited
id → String?
no setterinherited
included → List<PcoResource>
contains included items parsed into objects
no setterinherited
includedDesignations → List<PcoGivingDesignation>
no setter
includedLabels → List<PcoGivingLabel>
no setter
includedNote → PcoGivingNote?
no setter
includedRefund → PcoGivingRefund?
no setter
isRefundable → bool
no setter
isRefunded → bool
no setter
contains the links data returned by the api if present
no setterinherited
needsSave → bool
no setterinherited
paymentBrand ↔ 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.
getter/setter pair
paymentCheckDatedAt ↔ String
The check date for donations made by check. Example: 2000-01-01
getter/setter pair
paymentCheckNumber ↔ int
The check number for donations made by check.
getter/setter pair
paymentLast4 ↔ 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
getter/setter pair
paymentMethod ↔ String
Required. The payment method used to make a donation.
getter/setter pair
paymentMethodSub ↔ String
For cards, this will be the card subtype. Will be null for other payment method types.
getter/setter pair
paymentSourceId ↔ String
pass null to remove key from attributes
getter/setter pair
paymentStatus → String
no setter
pcoApplication ↔ String
latefinalinherited
personId ↔ String
pass null to remove key from attributes
getter/setter pair
receivedAt ↔ DateTime
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
getter/setter pair
relationships → ReadOnlyMapView<String, List<PcoResource>>
contains relationships parsed into objects even though the api sends relationship objects as Maps or Lists we always put them into lists for consistency
no setterinherited
resourceType ↔ String
all planning center resources must have a type
latefinalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
slug → String
no setterinherited
updateAllowed → List<String>
no setteroverride
updatedAt → DateTime
no setterinherited

Methods

coerceDouble(dynamic a) → double
inherited
coerceInt(dynamic a) → int
inherited
delete() → Future<PlanningCenterApiResponse<PlanningCenterApiData>>
inherited
filteredAttributes(List<String> allowedKeys) → Map<String, dynamic>
inherited
fromJson(Map<String, dynamic> data, {List<Map<String, dynamic>>? withIncluded}) → dynamic
Takes a full JSON:API Response Object (the contents of a "data" field) will clear and update id, apiPath, attributes and _relationships
inherited
getCampus({PcoGivingCampusQuery? query}) → Future<PcoCollection<PcoGivingCampus>>
Will get a collection of PcoGivingCampus objects (expecting one) using a path like this: https://api.planningcenteronline.com/giving/v2/donations/1/campus
getDesignations({PcoGivingDesignationQuery? query}) → Future<PcoCollection<PcoGivingDesignation>>
Will get a collection of PcoGivingDesignation objects (expecting many) using a path like this: https://api.planningcenteronline.com/giving/v2/donations/1/designations
getLabels({PcoGivingLabelQuery? query}) → Future<PcoCollection<PcoGivingLabel>>
Will get a collection of PcoGivingLabel objects (expecting many) using a path like this: https://api.planningcenteronline.com/giving/v2/donations/1/labels
getNote({PcoGivingNoteQuery? query}) → Future<PcoCollection<PcoGivingNote>>
Will get a collection of PcoGivingNote objects (expecting many) using a path like this: https://api.planningcenteronline.com/giving/v2/donations/1/note
getRefund({PcoGivingRefundQuery? query}) → Future<PcoCollection<PcoGivingRefund>>
Will get a collection of PcoGivingRefund objects (expecting many) using a path like this: https://api.planningcenteronline.com/giving/v2/donations/1/refund
handleIncludes(List<Map<String, dynamic>> included) → void
This function populates the relationships with typed resource objects based on the data in the included map of the json.
inherited
handleItem(Map<String, dynamic> data) → PcoResource?
inherited
handleRelationships(Map<String, dynamic> items, [List<Map<String, dynamic>> included = const []]) → Map<String, List<PcoResource>>
inherited
issueRefund(Object data) → Future<PlanningCenterApiResponse<PlanningCenterApiData>>
ACTION: issue_refund
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
save({Map<String, PcoResource>? withRelated, List<PcoResource>? withIncluded}) → Future<PlanningCenterApiResponse<PlanningCenterApiData>>
Many Planning Center endpoints allow or require additional relationships and/or included items to be sent with a create/update operation. Since these cannot always be determined by the automatic code generation, they may be included as arguments to the save operation.
inherited
toCreateResource() → Map<String, dynamic>
create the attributes Map for this object without the id field using only the attributes allowed in create (post) operations
inherited
toDataMap({Map<String, PcoResource>? withRelated, List<PcoResource>? withIncluded}) → Map<String, dynamic>
create a json-api Map for this object automatically selecting create or update based on the existence of the id field. Will result in something like this:
inherited
toIdResource() → Map<String, dynamic>
returns the simplest representation of this resource with only the type and the id:
inherited
toJson({dynamic includeAttributes = true, dynamic includeRelationships = false}) → Map<String, dynamic>
Some api requests only want the type and id of an object. In those cases, set includeAttributes to false or call toIdResource instead.
inherited
toString() → String
A string representation of this object.
inherited
toUpdateResource() → Map<String, dynamic>
create the attributes Map for this object using only the attributes allowed in update (patch) operations
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

canInclude → List<String>
possible includes with parameter ?include=a,b
no setter
canOrderBy → List<String>
possible orderings with parameter ?order=
no setter
canQuery → List<String>
possible queries using parameters like ?wherekey=value or ?wheregt|lt=value
no setter

Static Methods

get({String? id, PcoGivingDonationQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection of PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/donations
getAll({String? id, PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection containing ALL PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/donations
getAllFromBatch(String batchId, {String? id, PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection containing ALL PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/batches/$batchId/donations
getAllFromCampus(String campusId, {String? id, PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection containing ALL PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/campuses/$campusId/donations
getAllFromPaymentSource(String paymentSourceId, {String? id, PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection containing ALL PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/payment_sources/$paymentSourceId/donations
getAllFromPerson(String personId, {String? id, PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection containing ALL PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/people/$personId/donations
getFromBatch(String batchId, {String? id, PcoGivingDonationQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection of PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/batches/$batchId/donations
getFromCampus(String campusId, {String? id, PcoGivingDonationQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection of PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/campuses/$campusId/donations
getFromPaymentSource(String paymentSourceId, {String? id, PcoGivingDonationQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection of PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/payment_sources/$paymentSourceId/donations
getFromPerson(String personId, {String? id, PcoGivingDonationQuery? query, bool getAll = false, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoCollection<PcoGivingDonation>>
Will get a PcoCollection of PcoGivingDonation objects (expecting many) using a path like this: /giving/v2/people/$personId/donations
getSingle(String id, {PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoGivingDonation?>
Will get a single PcoGivingDonation object using a path like this: /giving/v2/donations/[id]
getSingleFromBatch(String batchId, String id, {PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoGivingDonation?>
Will get a single PcoGivingDonation object using a path like this: /giving/v2/batches/$batchId/donations/[id]
getSingleFromCampus(String campusId, String id, {PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoGivingDonation?>
Will get a single PcoGivingDonation object using a path like this: /giving/v2/campuses/$campusId/donations/[id]
getSingleFromPaymentSource(String paymentSourceId, String id, {PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoGivingDonation?>
Will get a single PcoGivingDonation object using a path like this: /giving/v2/payment_sources/$paymentSourceId/donations/[id]
getSingleFromPerson(String personId, String id, {PcoGivingDonationQuery? query, bool includeAllRelated = false, bool includeDesignations = false, bool includeLabels = false, bool includeNote = false, bool includeRefund = false}) → Future<PcoGivingDonation?>
Will get a single PcoGivingDonation object using a path like this: /giving/v2/people/$personId/donations/[id]