Item - Services API - Planning Center

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
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_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
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_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
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`