Every collection in every product is a query builder. This guide covers filtering, side-loading, sorting, pagination, and navigating between resources.
Builders are immutable: every method returns a new builder and leaves the original unchanged, so you can define a base query once and branch from it safely.
const active = pco.people.people.where('status', 'active');
const adults = active.where('child', false); // `active` is unchanged
const newest = active.order('-created_at').first();Names are snake_case exactly as in Planning Center’s API reference,
and every name (where fields, includes, order fields, filters, edges) is checked against the docs
for that resource. Pressing . or ' in your editor shows what’s available.
where: filter by attribute
// Equality: where[status]=active
pco.people.people.where('status', 'active');
// Comparison: where[created_at][gte]=2026-01-01
pco.people.people.where('created_at', 'gte', '2026-01-01');
// Ranges: call it twice
pco.people.people.where('birthdate', 'gte', '1990-01-01').where('birthdate', 'lt', '2000-01-01');
// Dates are sent as ISO 8601
pco.people.people.where('updated_at', 'gt', new Date(Date.now() - 24 * 60 * 60 * 1000));
// Search fields Planning Center documents as query parameters
pco.people.people.where('search_name_or_email', 'ada@example.com');- Operators are
gt,gte,lt, andlte. They’re only accepted on fields Planning Center lets you compare (usually dates, times, and some numbers). A field without operators is equality only, and passing an operator is a type error. - Value types come from the docs: booleans for boolean fields, numbers for numeric fields,
string | Datefor dates. - Calling
whereagain with the same field (and operator) replaces the earlier value. - Passing
undefinedornullas the value throws aPcoErrorinstead of silently dropping the condition, so a missing variable can’t turn a filtered query into “everything”.
Partial matches with %
Use % as a wildcard in a text where value for a partial match. Write it as-is: the library
percent-encodes every value for the URL (Tim% is sent as Tim%25), so Planning Center receives
exactly the % you wrote, and you never need to encode values yourself:
pco.people.people.where('first_name', 'Tim%'); // starts with "Tim": Tim, Timothy, ...Which fields honor wildcards is up to Planning Center, so test against your data. For searching
people, the documented search_name, search_name_or_email, and
search_name_or_email_or_phone_number fields are usually the better tool.
filter: named filters
Some endpoints accept named filters (?filter=future). The accepted names depend on the edge,
and they’re typed per edge:
pco.services.service_types.id('1').plans.filter('future');
pco.people.people.filter('admins');
pco.people.people.id('1').background_checks.filter('current', 'not_expired'); // filter=current,not_expiredRepeated calls add to the list. Some filters take an extra parameter (for example the People
created_since filter or the Services after and before plan filters). Pass it with
param(); check Planning Center’s docs for each filter’s parameter name:
pco.services.service_types.id('1').plans.filter('after').param('after', '2026-12-01');include: side-load related resources
include() asks Planning Center to embed related resources in the response’s included array,
saving a request per resource. Read them with related(resource, name), which returns an array
typed by the relationship:
const { data, related } = await pco.people.people
.include('emails', 'phone_numbers', 'primary_campus')
.list();
for (const person of data) {
const emails = related(person, 'emails'); // People.Email[]
const phones = related(person, 'phone_numbers'); // People.PhoneNumber[]
const [campus] = related(person, 'primary_campus'); // People.Campus | undefined
console.log(person.attributes.name, emails[0]?.attributes.address, campus?.attributes.name);
}related() always returns an array: empty when the relationship is missing or wasn’t included, one
element for a to-one relationship. The raw included array is on the result too.
For a single resource, pass include as an option:
const { data: plan, related } = await pco.services.service_types.id('1').plans.id('2').get({ include: ['plan_times'] });
const times = related(plan, 'plan_times'); // Services.PlanTime[]order: sort
pco.people.people.order('last_name'); // ascending
pco.people.people.order('-created_at'); // descending
pco.people.people.order('last_name', 'first_name'); // order=last_name,first_nameEach call replaces the previous order. Only fields the docs list as orderable are accepted.
Pagination
Planning Center pages results with per_page (1 to 100, default 25) and offset.
const page = await pco.people.people.perPage(50).offset(100).list();
page.data; // this page's resources
page.totalCount; // meta.total_count: matches across all pages
page.nextOffset; // offset of the next page, or undefined on the last page
page.meta; // the raw meta (can_include, can_order_by, ...)
page.links; // the raw links (self, next, ...)Usually you don’t page by hand. Pick the method that fits:
| Method | What it does |
|---|---|
list(options?) |
Fetches one page |
all(options?) |
Async-iterates every matching resource, following pagination |
pages(options?) |
Async-iterates page by page (each with its own included and related()) |
toArray(options?) |
Collects every matching resource into an array |
first(options?) |
Fetches the first match (per_page=1), or undefined |
count(options?) |
Returns the total number of matches (per_page=1) |
get(id, options?) |
Fetches one resource by id from this collection |
// Stream everything, 100 per request.
for await (const person of pco.people.people.where('status', 'active').all()) {
console.log(person.attributes.name);
}
// Need `included`? Iterate pages instead.
for await (const page of pco.people.people.include('emails').pages()) {
for (const person of page.data) console.log(page.related(person, 'emails').length);
}
// Limits
const firstThousand = await pco.people.people.toArray({ max: 1000 });
for await (const page of pco.people.people.pages({ maxPages: 3 })) console.log(page.data.length);
// Shortcuts
const newest = await pco.people.people.order('-created_at').first();
const total = await pco.people.people.where('child', true).count();all(), pages(), and toArray() request 100 per page unless you set perPage(). Breaking out
of a for await loop stops fetching.
Navigating nested resources
id(id) returns a reference to one resource. It has get(), update() and delete() (when the
resource supports them), action(), and one property per edge Planning Center documents for that
resource. Edges can be chained as deep as the URLs go:
// GET /people/v2/people/1/emails
await pco.people.people.id('1').emails.list();
// GET /people/v2/people/1/workflow_cards?filter=assigned
await pco.people.people.id('1').workflow_cards.filter('assigned').list();
// GET /services/v2/service_types/1/plans/2/team_members?filter=confirmed
await pco.services.service_types.id('1').plans.id('2').team_members.filter('confirmed').list();
// GET /groups/v2/groups/5/memberships?include=person
await pco.groups.groups.id('5').memberships.include('person').list();Edges that return a collection are full query builders (where, include, all(), …). The few
edges that return exactly one resource have get(), plus create() when Planning Center accepts
a POST there (for example starring a People list with pco.people.lists.id('1').star):
const { data: enrollment } = await pco.groups.groups.id('5').enrollment.get(); // data may be nullTo-one relationships documented as collections
Planning Center’s API documentation describes many to-one links as collections, for example a
person’s primary_campus or a Services item’s song and arrangement. They’re typed and
accessed as collections, so use list() (or first()) rather than get():
const [campus] = (await pco.people.people.id('1').primary_campus.list()).data;
const song = await pco.services.service_types.id('1').plans.id('2').items.id('3').song.first();The runtime accepts either response shape (a single resource or an array) for these edges, so this keeps working whichever one Planning Center returns.
Canonical URLs
When a resource type has its own top-level URL (People lists live at /people/v2/lists/{id}, for
example), .id() addresses it by that canonical URL even when you reached it through a nested
chain. Deep chains therefore only ever request URLs Planning Center documents, and .path on the
reference shows the URL that will be used.
Ids can be strings or numbers. Building a reference doesn’t send a request; only get(),
list(), and the other terminal methods do.
Edges that collide with method names
If an edge is named like a builder method (get, update, delete, action, edge, path, or
then), reach it with edge(). edge() works for any edge:
pco.people.people.id('1').edge('emails').list();The product root has the same escape hatch for root collections, and get() fetches the root
resource itself (usually the organization):
const { data: org } = await pco.services.get();
await pco.services.edge('service_types').list();Cancelling
Every terminal method accepts an AbortSignal:
const controller = new AbortController();
setTimeout(() => controller.abort(), 5_000);
await pco.people.people.list({ signal: controller.signal });
await pco.people.people.id('1').get({ signal: controller.signal, include: ['emails'] });
for await (const person of pco.people.people.all({ signal: controller.signal })) console.log(person.id);An aborted request rejects with the signal’s reason (an AbortError DOMException by default).
Anything else
param(key, value) sets any raw query parameter, for parameters the typed methods don’t cover:
pco.people.people.param('where[search_name_or_email_or_phone_number]', '555');The path property on any builder shows the URL path it targets, which helps when debugging.
Raw requests
For endpoints that aren’t in the docs at all, pco.request() is still authenticated, rate
limited, and retried:
import type { JsonApiDocument } from '@mackenly/planningcenterkit';
const me = await pco.request<JsonApiDocument>({ method: 'GET', path: '/people/v2/me' });
const page = await pco.request<JsonApiDocument>({
method: 'GET',
path: '/people/v2/people',
query: { 'where[search_name_or_email]': 'ada', per_page: 10 },
version: '2026-10-05', // raw requests send no X-PCO-API-Version unless you set one
});