---
title: "Batch (Giving)"
description: "A Batch is a collection of Donations."
---

> 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.

# Batch (Giving)

A `Batch` is a collection of `Donation`s. 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 `Donation`s 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 `Donation`s 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 `Donation`s are logged and visible to Giving admins.

With all of that in mind, you can use `Batch`es in one of two ways:

  1.  Create an uncommitted `Batch`, add `Donation`s to it, then commit the `Batch`.
  2.  Create a `Batch` with a least one donation, commit it, then add more `Donation`s 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 `Donation`s are made visible to donors. Any `Donation`s 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 `Batch`es that the Giving admins might be creating on their own.

| Property | Value |
| --- | --- |
| Product | [Giving](/reference/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](https://api.planningcenteronline.com/docs/apps/giving/versions/2019-10-18/vertices/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](/guides/querying/); 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](#status). |
| `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` {#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](/reference/giving/batch-group/) | 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](/reference/giving/batch-group/) | `committed`, `in_progress` |
| `batches` on [Person](/reference/giving/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](/reference/giving/batch-group/) | Collection |  | No |
| `ref.donations` | [Donation](/reference/giving/donation/) | Collection |  | Yes |
| `ref.owner` | [Person](/reference/giving/person/) | Collection |  | No |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `pco.giving.batches`, `batches` on [BatchGroup](/reference/giving/batch-group/) |
| 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](/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/batches/{batch_id}/commit` | Used to commit an in progress batch. |

## Example

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

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

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