API
⌘K
My Developer Account

Item

An item in a plan.

Example Request 

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

View in API Explorer →

Example Object 

{
  "type": "Item",
  "id": "1",
  "attributes": {
    "created_at": "2000-01-01T12:00:00Z",
    "custom_arrangement_sequence": [],
    "custom_arrangement_sequence_full": [],
    "custom_arrangement_sequence_short": [],
    "description": "string",
    "html_details": "string",
    "item_type": "string",
    "key_name": "string",
    "length": 1,
    "sequence": 1,
    "service_position": "string",
    "title": "string",
    "updated_at": "2000-01-01T12:00:00Z"
  },
  "relationships": {
    "plan": {
      "data": {
        "type": "Plan",
        "id": "1"
      }
    },
    "song": {
      "data": {
        "type": "Song",
        "id": "1"
      }
    },
    "arrangement": {
      "data": {
        "type": "Arrangement",
        "id": "1"
      }
    },
    "key": {
      "data": {
        "type": "Key",
        "id": "1"
      }
    },
    "selected_layout": {
      "data": {
        "type": "Layout",
        "id": "1"
      }
    },
    "selected_background": {
      "data": {
        "type": "Attachment",
        "id": "1"
      }
    }
  }
}

Attributes

Name Type Description
created_at date_time
custom_arrangement_sequence array

An array of strings containing a label and a number describing the section:

['Verse 1', 'Chorus 1', 'Verse 2']
custom_arrangement_sequence_full array
custom_arrangement_sequence_short array
description string
html_details string
id primary_key
item_type string

There are 4 possible values:

  • song: The item is a song

  • header: The item is a header

  • media: The item is a piece of media

  • item: The default item type

This value can only be set when an item is created. The only value that you can pass is header. If no value is passed then item will be used. To create a media item you'll attach a video media to the item, and to create a song item, you'll attach a song.
key_name string
length integer
sequence integer
service_position string

There are 3 possible values:

  • pre: the item happens before the service starts

  • post: the item happens after the service ends

  • during: the item happens during the service
title string
updated_at date_time

Relationships

Name Type Association Type Note
plan Plan to_one
song Song to_one
arrangement Arrangement to_one
key Key to_one
selected_layout Layout to_one
selected_background Attachment to_one

Can Include

Parameter Value Description Assignable
include arrangement

include associated arrangement

 create and update
include item_assignments

include associated item_assignments
include item_notes

include associated item_notes
include item_times

include associated item_times
include key

include associated key

 create and update
include media

include associated media

 create and update
include selected_attachment

include associated selected_attachment

 create and update
include song

include associated song

 create and update

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/{plan_id}/items

Reading

HTTP Method Endpoint
GET /services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{id}

Creating

HTTP Method Endpoint Assignable Attributes
POST /services/v2/service_types/{service_type_id}/plans/{plan_id}/items
  • arrangement_id
  • custom_arrangement_sequence
  • description
  • html_details
  • key_id
  • length
  • selected_layout_id
  • service_position
  • song_id
  • title
  • item_type
  • sequence

Updating

HTTP Method Endpoint Assignable Attributes
PATCH /services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{id}
  • arrangement_id
  • custom_arrangement_sequence
  • description
  • html_details
  • key_id
  • length
  • selected_layout_id
  • service_position
  • song_id
  • title

Deleting

HTTP Method Endpoint
DELETE /services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{id}

Associations

HTTP Method Endpoint Returns Details Filter By
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/arrangement Arrangement
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/attachments Attachment
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/custom_slides CustomSlide
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/item_assignments ItemAssignment
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/item_notes ItemNote
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/item_times ItemTime
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/key Key
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/media Media
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/selected_attachment Attachment
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/selected_background Attachment
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items/{item_id}/song Song

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}/items Live
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plans/{plan_id}/items Plan
GET https://api.planningcenteronline.com/services/v2/service_types/{service_type_id}/plan_templates/{plan_template_id}/items PlanTemplate
GET https://api.planningcenteronline.com/services/v2/songs/{song_id}/last_scheduled_item Song

The Song's most recently scheduled Item in a given Service Type. Requires a service_type query parameter. e.g. ?service_type=789