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:
- Create an uncommitted
Batch, addDonations to it, then commit theBatch. - Create a
Batchwith a least one donation, commit it, then add moreDonations 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;