---
title: "Plan (Services)"
description: "A single plan within a Service Type."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plan (Services)

A single plan within a Service Type.

| Property | Value |
| --- | --- |
| Product | [Services](/reference/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](https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/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](/guides/querying/); 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](/reference/services/attachment-type/) | No |
| `created_by` | To one | [Person](/reference/services/person/) | No |
| `linked_publishing_episode` | To one | `LinkedPublishingEpisode` | No |
| `next_plan` | To one | [Plan](/reference/services/plan/) | No |
| `previous_plan` | To one | [Plan](/reference/services/plan/) | No |
| `series` | To one | [Series](/reference/services/series/) | Yes |
| `service_type` | To one | [ServiceType](/reference/services/service-type/) | No |
| `updated_by` | To one | [Person](/reference/services/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](/reference/services/service-type/) | `after`, `before`, `future`, `no_dates`, `past` |
| `unscoped_plans` on [ServiceType](/reference/services/service-type/) | `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](/reference/services/attachment/) | Collection | `attachable_type`, `extensions` | No |
| `ref.attachments` | [Attachment](/reference/services/attachment/) | Collection |  | Yes |
| `ref.attendances` | [Attendance](/reference/services/attendance/) | Collection |  | No |
| `ref.contributors` | [Contributor](/reference/services/contributor/) | Collection |  | No |
| `ref.items` | [Item](/reference/services/item/) | Collection |  | Yes |
| `ref.live` | [Live](/reference/services/live/) | Collection |  | No |
| `ref.my_schedules` | [Schedule](/reference/services/schedule/) | Collection |  | No |
| `ref.needed_positions` | [NeededPosition](/reference/services/needed-position/) | Collection |  | Yes |
| `ref.next_plan` | [Plan](/reference/services/plan/) | Collection |  | No |
| `ref.notes` | [PlanNote](/reference/services/plan-note/) | Collection | `team` | Yes |
| `ref.plan_times` | [PlanTime](/reference/services/plan-time/) | Collection |  | Yes |
| `ref.previous_plan` | [Plan](/reference/services/plan/) | Collection |  | No |
| `ref.series` | [Series](/reference/services/series/) | Collection |  | No |
| `ref.signup_teams` | [Team](/reference/services/team/) | Collection |  | No |
| `ref.team_members` | [PlanPerson](/reference/services/plan-person/) | Collection | `confirmed`, `not_archived`, `not_declined`, `not_deleted` | Yes |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `plans` on [ServiceType](/reference/services/service-type/) |
| 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](/guides/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

```ts
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;
```

Source: https://planningcenterkit.mackenly.com/reference/services/plan/index.mdx
