Skip to content

Plan (Services)

A single plan within a Service Type.

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;

Type to search…

↑↓ navigate↵ selectEsc close