Batch

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.

curl https://api.planningcenteronline.com/giving/v2/batches

{
  "type": "Batch",
  "id": "1",
  "attributes": {
    "committed_at": "2000-01-01T12:00:00Z",
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "donations_count": 1,
    "status": "string",
    "total_cents": 1,
    "total_currency": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "batch_group": {
      "data": {
        "type": "BatchGroup",
        "id": "1"
      }
    }
  }
}