Plan
A single plan within a Service Type.
Example Request
curl https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans
Example Object
{
"type": "Plan",
"id": "1",
"attributes": {
"can_view_order": true,
"created_at": "2000-01-01T12:00:00Z",
"dates": "string",
"files_expire_at": "2000-01-01T12:00:00Z",
"items_count": 1,
"last_time_at": "2000-01-01T12:00:00Z",
"multi_day": true,
"needed_positions_count": 1,
"other_time_count": 1,
"permissions": "string",
"plan_notes_count": 1,
"plan_people_count": 1,
"planning_center_url": "string",
"prefers_order_view": true,
"public": true,
"public_by_schedule": true,
"rehearsable": true,
"rehearsal_time_count": 1,
"reminders_disabled": true,
"series_title": "string",
"service_time_count": 1,
"short_dates": "string",
"sort_date": "2000-01-01T12:00:00Z",
"title": "string",
"total_length": 1,
"updated_at": "2000-01-01T12:00:00Z"
},
"relationships": {
"service_type": {
"data": {
"type": "ServiceType",
"id": "1"
}
},
"previous_plan": {
"data": {
"type": "Plan",
"id": "1"
}
},
"next_plan": {
"data": {
"type": "Plan",
"id": "1"
}
},
"series": {
"data": {
"type": "Series",
"id": "1"
}
},
"created_by": {
"data": {
"type": "Person",
"id": "1"
}
},
"updated_by": {
"data": {
"type": "Person",
"id": "1"
}
},
"linked_publishing_episode": {
"data": {
"type": "LinkedPublishingEpisode",
"id": "1"
}
},
"attachment_types": {
"data": [
{
"type": "AttachmentType",
"id": "1"
}
]
}
}
}
Attributes
| Name | Type | Description |
|---|---|---|
can_view_order |
boolean |
|
created_at |
date_time |
|
dates |
string |
The full date string representing all Service Time dates. |
files_expire_at |
date_time |
A date 15 days after the last service time. Returns in the time zone specified in your organization's localization settings |
id |
primary_key |
|
items_count |
integer |
The total number of items, including regular items, songs, media, and headers, that the current user can see in the plan. |
last_time_at |
date_time |
Returns in the time zone specified in your organization's localization settings |
multi_day |
boolean |
|
needed_positions_count |
integer |
|
other_time_count |
integer |
|
permissions |
string |
The current user's permissions for this plan's Service Type. |
plan_notes_count |
integer |
|
plan_people_count |
integer |
|
planning_center_url |
string |
|
prefers_order_view |
boolean |
|
public |
boolean |
True if Public Access has been enabled. |
public_by_schedule |
boolean |
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 |
|
rehearsal_time_count |
integer |
|
reminders_disabled |
boolean |
|
series_title |
string |
|
service_time_count |
integer |
|
short_dates |
string |
The shortened date string representing all Service Time dates. Months are abbreviated, and the year is omitted. |
sort_date |
date_time |
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 |
|
total_length |
integer |
The total of length of all items, excluding pre-service and post-service items. |
updated_at |
date_time |
Relationships
| Name | Type | Association Type | Note |
|---|---|---|---|
| service_type | ServiceType | to_one | |
| previous_plan | Plan | to_one | |
| next_plan | Plan | to_one | |
| series | Series | to_one | |
| created_by | Person | to_one | |
| updated_by | Person | to_one | |
| linked_publishing_episode | LinkedPublishingEpisode | to_one | |
| attachment_types | AttachmentType | to_many |
Can Include
| Parameter | Value | Description | Assignable |
|---|---|---|---|
| include | contributors | include associated contributors |
|
| include | my_schedules | include associated my_schedules |
|
| include | plan_times | include associated plan_times |
|
| include | series | include associated series |
create and update |
Order By
| Parameter | Value | Type | Description |
|---|---|---|---|
| order | created_at | string | prefix with a hyphen (-created_at) to reverse the order |
| order | sort_date | string | prefix with a hyphen (-sort_date) to reverse the order |
| order | title | string | prefix with a hyphen (-title) to reverse the order |
| order | updated_at | string | prefix with a hyphen (-updated_at) to reverse the order |
Query By
| Name | Parameter | Type | Description | Example |
|---|---|---|---|---|
| created_at | where[created_at] |
date_time | Query on a specific created_at |
?where[created_at]=2000-01-01T12:00:00Z |
| id | where[id] |
primary_key | Query on a specific id |
?where[id]=primary_key |
| series_title | where[series_title] |
string | Query on a specific series_title |
?where[series_title]=string |
| title | where[title] |
string | Query on a specific title |
?where[title]=string |
| 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 | /services/v2/service_types/{service_type_id}/plans |
Reading
| HTTP Method | Endpoint |
|---|---|
| GET | /services/v2/service_types/{service_type_id}/plans/{id} |
Creating
| HTTP Method | Endpoint | Assignable Attributes |
|---|---|---|
| POST | /services/v2/service_types/{service_type_id}/plans |
|
Updating
| HTTP Method | Endpoint | Assignable Attributes |
|---|---|---|
| PATCH | /services/v2/service_types/{service_type_id}/plans/{id} |
|
Deleting
| HTTP Method | Endpoint |
|---|---|
| DELETE | /services/v2/service_types/{service_type_id}/plans/{id} |
Actions
| HTTP Method | Endpoint | Description |
|---|---|---|
| POST | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/autoschedule |
Auto-schedule for a team. Returns a collection of scheduled |
Auto-schedule for a team. Returns a collection of scheduled It expects a |
||
| POST | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/import |
Apply a Plan or PlanTemplate to this Plan |
This action copies the team members, needed positions, items, and notes from a source Plan or PlanTemplate into this (already existing) Plan. Accepted attributes:
-
Permissions: requires scheduler on the target plan's service type (and on every
Returns a |
||
| POST | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/item_reorder |
Reorder plan items in one request. |
This can be used to reorder all items in a plan in one request. It expects a
On success you will get back a |
||
Associations
| HTTP Method | Endpoint | Returns | Details | Filter By |
|---|---|---|---|---|
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/all_attachments |
Attachment |
|
|
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/attachments |
Attachment | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/attendances |
Attendance | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/contributors |
Contributor | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items |
Item | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/live |
Live | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/my_schedules |
Schedule | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/needed_positions |
NeededPosition | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/next_plan |
Plan | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/notes |
PlanNote |
|
|
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/plan_times |
PlanTime | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/previous_plan |
Plan | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/series |
Series | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/signup_teams |
Team | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/team_members |
PlanPerson |
|
Belongs To
| HTTP Method | Endpoint | Association | Details | Filter By |
|---|---|---|---|---|
| GET | https://api.planningcenteronline.com/services/v2/series/{series_id}/plans/{plan_id}/live/{live_id}/watchable_plans |
Live | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/next_plan |
Plan | ||
| GET | https://api.planningcenteronline.com/services/v2/people/{person_id}/plan_people/{plan_person_id}/plan |
PlanPerson | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/previous_plan |
Plan | ||
| GET | https://api.planningcenteronline.com/services/v2/series/{series_id}/plans |
Series | ||
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans |
ServiceType |
|
|
| GET | https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/unscoped_plans |
ServiceType |
|