BatchGroup

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.

Example Request

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

View in API Explorer →

Example Object

{
  "type": "BatchGroup",
  "id": "1",
  "attributes": {
    "committed": true,
    "created_at": "2000-01-01T12:00:00Z",
    "description": "string",
    "status": "string",
    "total_cents": 1,
    "total_currency": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {}
}

Attributes

Name	Type	Description
`committed`	`boolean`	Returns `true` if a batch group has been committed, and `false` if it hasn't.
`created_at`	`date_time`	The date and time at which a batch group was created. Example: `2000-01-01T12:00:00Z`
`description`	`string`	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.
`id`	`primary_key`	The unique identifier for a batch group. For batches and batch groups, these identifiers are unique not across all of Planning Center, but only per organization. As such, it is possible to see the same batch group `id` in multiple organizations.
`status`	`string`	One of `in_progress`, `updating`, or `committed`. The `updating` state is temporary and describes a BatchGroup that is currently being changed in some way (e.g. moving from `in_progress` to `committed`). Certain changes to BatchGroups in this state (or their Batches or Donations) will be restricted until the BatchGroup has finished updating.
`total_cents`	`integer`	The gross total of cents donated within the batch group. Factors in all donations made to each batch within the group.
`total_currency`	`string`	The currency used to calculate `total_cents`.
`updated_at`	`date_time`	The date and time at which a batch group was last updated. Example: `2000-01-01T12:00:00Z`

Can Include

Parameter	Value	Description	Assignable
include	owner	include associated owner

Order By

Parameter	Value	Type	Description
order	updated_at	string	prefix with a hyphen (-updated_at) to reverse the order

Query By

Name	Parameter	Type	Description	Example
updated_at	`where[updated_at]`	date_time	Query on a specific updated_at	`?where[updated_at]=2000-01-01T12:00:00Z`

Pagination

Name	Parameter	Type	Description
per_page	per_page	integer	how many records to return per page (min=1, max=100, default=25)
offset	offset	integer	get results from given offset

Endpoints

Listing

HTTP Method	Endpoint
GET	`/giving/v2/batch_groups`

Reading

HTTP Method	Endpoint
GET	`/giving/v2/batch_groups/{id}`

Creating

HTTP Method	Endpoint	Assignable Attributes
POST	`/giving/v2/batch_groups`	description

Updating

HTTP Method	Endpoint	Assignable Attributes
PATCH	`/giving/v2/batch_groups/{id}`	description

Deleting

HTTP Method	Endpoint
DELETE	`/giving/v2/batch_groups/{id}`

Actions

HTTP Method	Endpoint	Description
POST	`https://api.planningcenteronline.com/giving/v2/batch_groups/{batch_group_id}/commit`	Used to commit an in progress batch group.

Associations

HTTP Method	Endpoint	Returns	Details	Filter By
GET	`https://api.planningcenteronline.com/giving/v2/batch_groups/{batch_group_id}/batches`	Batch		`committed` `in_progress`
GET	`https://api.planningcenteronline.com/giving/v2/batch_groups/{batch_group_id}/owner`	Person

Belongs To

HTTP Method	Endpoint	Association	Filter By
GET	`https://api.planningcenteronline.com/giving/v2/batches/{batch_id}/batch_group`	Batch
GET	`https://api.planningcenteronline.com/giving/v2/batch_groups`	Organization	`committed` `in_progress`
GET	`https://api.planningcenteronline.com/giving/v2/people/{person_id}/batch_groups`	Person	`committed` `in_progress`