---
title: "BatchGroup (Giving)"
description: "A BatchGroup is a collection of Batches."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BatchGroup (Giving)

A `BatchGroup` is a collection of `Batch`es.

`BatchGroup`s are an optional way of organizing your `Batch`es 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 `Batch`es, 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](/reference/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](https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/batch_group) |

## 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](/guides/querying/); 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](#status). |
| `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` {#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](/reference/giving/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](/reference/giving/batch/) | Collection | `committed`, `in_progress` | Yes |
| `ref.owner` | [Person](/reference/giving/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](/guides/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

```ts
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;
```

Source: https://planningcenterkit.mackenly.com/reference/giving/batch-group/index.mdx
