Skip to content

Batch (Giving)

A Batch is a collection of Donations.

A Batch is a collection of Donations. When creating Donation’s via the API, you’re required to put them in a Batch.

When a Batch is first created, it’s in the in_progress or “uncommitted” state. You can freely add/remove/modify Donations in this Batch and they won’t show up in a donor’s donation history online, they won’t appear in any donor statements issued by the Giving admin, and changes to these donations are not flagged in the system log. Think of it as a staging area for donations.

When a Batch is committed (see more in the Actions section), all of the Donations within it are also marked as “committed”. At that point, they’re visible to donors in their online history, and any further edits made to those Donations are logged and visible to Giving admins.

With all of that in mind, you can use Batches in one of two ways:

  1. Create an uncommitted Batch, add Donations to it, then commit the Batch.
  2. Create a Batch with a least one donation, commit it, then add more Donations to it.

In both cases, the end result is the same. The main difference is that option #2 does not provide you/other admins the opportunity to fix any mistakes before changes are logged and Donations are made visible to donors. Any Donations added to a committed Batch will automatically be committed as well. Note, batches can’t be committed until they have at least one donation.

Whichever route you decide to take, it’s helpful to make use of the Batch’s description to help differentiate these groupings from each other and from other Batches that the Giving admins might be creating on their own.

Property Value
Product Giving (pco.giving, API version 2019-10-18)
Resource type Batch
TypeScript Giving.Batch, attributes Giving.BatchAttributes, schema Giving.BatchSchema
Planning Center path /giving/v2/batches
Planning Center docs Batch

How to reach it

Client path Returns Filters Create
pco.giving.batches Collection committed, in_progress Yes
pco.giving.batch_groups.id(batchGroupId).batches Collection committed, in_progress Yes
pco.giving.people.id(personId).batches Collection committed, in_progress No

From a collection, .id(batchId) addresses one Batch: pco.giving.batches.id(batchId). Collections support where, include, order, and pagination; single resources have get().

Attributes

On Giving.BatchAttributes. Every resource also has id and type ('Batch') next to its attributes.

Name Type Description
committed_at string | null The date and time that a batch was committed at. If it’s null, the batch is still in progress or updating. Example: 2000-01-01T12:00:00Z
created_at string | null The date and time at which a batch was created. Example: 2000-01-01T12:00:00Z
description string | null A brief description of what a batch is for. This is displayed in Giving to help differentiate different batches from one another. If no description is provided for a batch, it will be referred to as Untitled batch within Giving.
donations_count number | null Only available when requested with the ?fields param
status string | null See details.
total_cents number | null The gross total of cents donated within the batch.
total_currency string | null The currency used to calculate total_cents.
updated_at string | null The date and time at which a batch was last updated. Example: 2000-01-01T12:00:00Z

Attribute details

status

One of in_progress, updating, or committed. The updating state is temporary and describes a Batch that is currently being changed in some way (e.g. moving from in_progress to committed). Certain changes to Batches in this state (or their Donations) will be restricted until the Batch has finished updating.

Relationships and includes

Side-load with include() (or get({ include })) and read with related(resource, name): batch_group, owner.

Relationship Type To Includable
batch_group To one BatchGroup Yes

Querying

Where

where(field, value) for equality; where(field, op, value) with the operators listed.

Field Value type Operators
committed_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: committed_at, updated_at.

Filters

filter(...) names depend on the edge you query through:

Edge Filters
pco.giving.batches committed, in_progress
batches on BatchGroup committed, in_progress
batches on Person committed, in_progress

Edges

Follow these from one Batch, ref = pco.giving.batches.id(batchId):

Edge Leads to Returns Filters Create
ref.batch_group BatchGroup Collection No
ref.donations Donation Collection Yes
ref.owner Person Collection No

Writing

Property Value
Create Yes, create() on pco.giving.batches, batches on BatchGroup
Update Yes, update() on a reference
Delete Yes, delete() on a reference

Create attributes

Typed as Giving.BatchSchema['create'].

Attribute Type
batch_group_id string
description string | null

Update attributes

Typed as Giving.BatchSchema['update'].

Attribute Type
batch_group_id string
description 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
commit POST /giving/v2/batches/{batch_id}/commit Used to commit an in progress batch.

Example

import type { Giving } from '@mackenly/planningcenterkit';

const page = await pco.giving.batches.order('committed_at').perPage(25).list();
const items: Giving.Batch[] = page.data;

Type to search…

↑↓ navigate↵ selectEsc close