A single plan within a Service Type.
| Property | Value |
|---|---|
| Product | Services (pco.services, API version 2018-11-01) |
| Resource type | Plan |
| TypeScript | Services.Plan, attributes Services.PlanAttributes, schema Services.PlanSchema |
| Planning Center path | /services/v2/service_types/{service_type_id}/plans |
| Planning Center docs | Plan |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.services.series.id(seriesId).plans.id(planId).live.id(liveId).watchable_plans |
Collection | No | |
pco.services.series.id(seriesId).plans.id(planId).next_plan |
Collection | No | |
pco.services.series.id(seriesId).plans.id(planId).previous_plan |
Collection | No | |
pco.services.people.id(personId).plan_people.id(planPersonId).plan |
Collection | No | |
pco.services.series.id(seriesId).plans |
Collection | No | |
pco.services.service_types.id(serviceTypeId).plans |
Collection | after, before, future, no_dates, past |
Yes |
pco.services.service_types.id(serviceTypeId).unscoped_plans |
Collection | deleted |
No |
From a collection, .id(planId) addresses one Plan: pco.services.series.id(seriesId).plans.id(planId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On Services.PlanAttributes. Every resource also has id and type ('Plan') next to its attributes.
| Name | Type | Description |
|---|---|---|
can_view_order |
boolean | null |
|
created_at |
string | null |
|
dates |
string | null |
The full date string representing all Service Time dates. |
files_expire_at |
string | null |
A date 15 days after the last service time. Returns in the time zone specified in your organization’s localization settings |
items_count |
number | null |
The total number of items, including regular items, songs, media, and headers, that the current user can see in the plan. |
last_time_at |
string | null |
Returns in the time zone specified in your organization’s localization settings |
multi_day |
boolean | null |
|
needed_positions_count |
number | null |
|
other_time_count |
number | null |
|
permissions |
string | null |
The current user’s permissions for this plan’s Service Type. |
plan_notes_count |
number | null |
|
plan_people_count |
number | null |
|
planning_center_url |
string | null |
|
prefers_order_view |
boolean | null |
|
public |
boolean | null |
True if Public Access has been enabled. |
public_by_schedule |
boolean | null |
True if the plan is currently auto-published because the Service Type has scheduled publish enabled and the plan’s service date has arrived in the organization’s timezone. |
rehearsable |
boolean | null |
|
rehearsal_time_count |
number | null |
|
reminders_disabled |
boolean | null |
|
series_title |
string | null |
|
service_time_count |
number | null |
|
short_dates |
string | null |
The shortened date string representing all Service Time dates. Months are abbreviated, and the year is omitted. |
sort_date |
string | null |
A time representing the chronological first Service Time, used to sort plan chronologically. If no Service Times exist, it uses Rehearsal Times, then Other Times, then NOW. Returns in the time zone specified in your organization’s localization settings |
title |
string | null |
|
total_length |
number | null |
The total of length of all items, excluding pre-service and post-service items. |
updated_at |
string | null |
Relationships and includes
Side-load with include() (or get({ include })) and read with related(resource, name): contributors, my_schedules, plan_times, series.
| Relationship | Type | To | Includable |
|---|---|---|---|
attachment_types |
To many | AttachmentType | No |
created_by |
To one | Person | No |
linked_publishing_episode |
To one | LinkedPublishingEpisode |
No |
next_plan |
To one | Plan | No |
previous_plan |
To one | Plan | No |
series |
To one | Series | Yes |
service_type |
To one | ServiceType | No |
updated_by |
To one | Person | No |
Querying
Where
where(field, value) for equality; where(field, op, value) with the operators listed.
| Field | Value type | Operators |
|---|---|---|
created_at |
string | Date |
gt, gte, lt, lte |
id |
string |
Equality only |
series_title |
string |
Equality only |
title |
string |
Equality only |
updated_at |
string | Date |
gt, gte, lt, lte |
Order
order(...) accepts these fields, ascending, or descending with a - prefix: created_at, sort_date, title, updated_at.
Filters
filter(...) names depend on the edge you query through:
| Edge | Filters |
|---|---|
plans on ServiceType |
after, before, future, no_dates, past |
unscoped_plans on ServiceType |
deleted |
Edges
Follow these from one Plan, ref = pco.services.series.id(seriesId).plans.id(planId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.all_attachments |
Attachment | Collection | attachable_type, extensions |
No |
ref.attachments |
Attachment | Collection | Yes | |
ref.attendances |
Attendance | Collection | No | |
ref.contributors |
Contributor | Collection | No | |
ref.items |
Item | Collection | Yes | |
ref.live |
Live | Collection | No | |
ref.my_schedules |
Schedule | Collection | No | |
ref.needed_positions |
NeededPosition | Collection | Yes | |
ref.next_plan |
Plan | Collection | No | |
ref.notes |
PlanNote | Collection | team |
Yes |
ref.plan_times |
PlanTime | Collection | Yes | |
ref.previous_plan |
Plan | Collection | No | |
ref.series |
Series | Collection | No | |
ref.signup_teams |
Team | Collection | No | |
ref.team_members |
PlanPerson | Collection | confirmed, not_archived, not_declined, not_deleted |
Yes |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on plans on ServiceType |
| Update | Yes, update() on a reference |
| Delete | Yes, delete() on a reference |
Create attributes
Typed as Services.PlanSchema['create'].
| Attribute | Type |
|---|---|
public |
boolean | null |
series_id |
string |
series_title |
string | null |
title |
string | null |
Update attributes
Typed as Services.PlanSchema['update'].
| Attribute | Type |
|---|---|
public |
boolean | null |
reminders_disabled |
boolean | null |
series_id |
string |
series_title |
string | null |
title |
string | null |
See Writing data.
Actions
Run with ref.action(name, body?). Bodies are untyped: see Planning Center’s docs for each action.
| Action | Path | Description |
|---|---|---|
autoschedule |
POST /services/v2/service_types/{service_type_id}/plans/{plan_id}/autoschedule |
Auto-schedule for a team. Returns a collection of scheduled PlanPersonAutoscheduleVertex |
import |
POST /services/v2/service_types/{service_type_id}/plans/{plan_id}/import |
Apply a Plan or PlanTemplate to this Plan |
item_reorder |
POST /services/v2/service_types/{service_type_id}/plans/{plan_id}/item_reorder |
Reorder plan items in one request. |
Example
import type { Services } from '@mackenly/planningcenterkit';
const seriesId = '1'; // Series id
const page = await pco.services.series.id(seriesId).plans.order('created_at').perPage(25).list();
const items: Services.Plan[] = page.data;