A BatchGroup is a collection of Batches.
BatchGroups are an optional way of organizing your Batches into groups that share common characteristics. These are completely customizable and can be used in whatever way makes sense to your organization’s workflow.
Similarly to Batches, you can commit (see more in the Actions section) a BatchGroup, and by doing so, all Batches and Donations contained in the BatchGroup will also be committed.
| Property | Value |
|---|---|
| Product | Giving (pco.giving, API version 2019-10-18) |
| Resource type | BatchGroup |
| TypeScript | Giving.BatchGroup, attributes Giving.BatchGroupAttributes, schema Giving.BatchGroupSchema |
| Planning Center path | /giving/v2/batch_groups |
| Planning Center docs | BatchGroup |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.giving.batch_groups |
Collection | committed, in_progress |
Yes |
pco.giving.batches.id(batchId).batch_group |
Collection | No | |
pco.giving.people.id(personId).batch_groups |
Collection | committed, in_progress |
No |
From a collection, .id(batchGroupId) addresses one BatchGroup: pco.giving.batch_groups.id(batchGroupId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On Giving.BatchGroupAttributes. Every resource also has id and type ('BatchGroup') next to its attributes.
| Name | Type | Description |
|---|---|---|
committed |
boolean | null |
Returns true if a batch group has been committed, and false if it hasn’t. |
created_at |
string | null |
The date and time at which a batch group was created. Example: 2000-01-01T12:00:00Z |
description |
string | null |
A brief description of what a batch group is for. This is displayed in Giving to help differentiate different batch groups from one another. If no description is provided for a batch group, it will be referred to as Untitled group within Giving. |
status |
string | null |
See details. |
total_cents |
number | null |
The gross total of cents donated within the batch group. Factors in all donations made to each batch within the group. |
total_currency |
string | null |
The currency used to calculate total_cents. |
updated_at |
string | null |
The date and time at which a batch group was last updated. Example: 2000-01-01T12:00:00Z |
Attribute details
status
One of uncommitted, updating, or committed. The updating state is temporary and describes a BatchGroup that is currently being changed in some way (e.g. moving from uncommitted to committed). Certain changes to BatchGroups in this state (or their Batches or Donations) will be restricted until the BatchGroup has finished updating.
Relationships and includes
Side-load with include() (or get({ include })) and read with related(resource, name): owner.
Querying
Where
where(field, value) for equality; where(field, op, value) with the operators listed.
| Field | Value type | Operators |
|---|---|---|
description |
string |
Equality only |
updated_at |
string | Date |
gt, gte, lt, lte |
Order
order(...) accepts these fields, ascending, or descending with a - prefix: updated_at.
Filters
filter(...) names depend on the edge you query through:
| Edge | Filters |
|---|---|
pco.giving.batch_groups |
committed, in_progress |
batch_groups on Person |
committed, in_progress |
Edges
Follow these from one BatchGroup, ref = pco.giving.batch_groups.id(batchGroupId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.batches |
Batch | Collection | committed, in_progress |
Yes |
ref.owner |
Person | Collection | No |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on pco.giving.batch_groups |
| Update | Yes, update() on a reference |
| Delete | Yes, delete() on a reference |
Create attributes
Typed as Giving.BatchGroupSchema['create'].
| Attribute | Type |
|---|---|
description |
string | null |
Update attributes
Typed as Giving.BatchGroupSchema['update'].
| Attribute | Type |
|---|---|
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/batch_groups/{batch_group_id}/commit |
Used to commit an in progress batch group. |
Example
import type { Giving } from '@mackenly/planningcenterkit';
const page = await pco.giving.batch_groups.order('updated_at').perPage(25).list();
const items: Giving.BatchGroup[] = page.data;