API
⌘K
My Developer Account

Plan

A single plan within a Service Type.

Example Request 

curl https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans

View in API Explorer →

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,
    "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.
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
  • title
  • public
  • series_id
  • series_title

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /services/v2/service_types/{service_type_id}/plans/{id}
  • title
  • public
  • series_id
  • series_title
  • reminders_disabled

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 PlanPersonAutoscheduleVertex
POST https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/import_template

Import template to plan
POST https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/item_reorder

Reorder plan items in one request.

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
  • attachable_type

    filter attachments by their attachable_type as specified in the attachable_type parameter. Default: ["ServiceType", "Plan", "Item", "Media", "Song", "Arrangement", "Key"]. e.g. ?filter=attachable_type&attachable_type=Plan,ServiceType

  • extensions

    filter to attachments with a file extension specified in the extensions parameter. e.g. ?filter=extensions&extensions=pdf,txt
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
  • team
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
  • confirmed
  • not_archived
  • not_declined
  • not_deleted

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
  • after

    filter to plans with a time beginning after the after parameter

  • before

    filter to plans with a time beginning before the before parameter

  • future
  • no_dates
  • past
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/unscoped_plans ServiceType
  • deleted