Skip to content

Item (Services)

An item in a plan.

An item in a plan.

Property Value
Product Services (pco.services, API version 2018-11-01)
Resource type Item
TypeScript Services.Item, attributes Services.ItemAttributes, schema Services.ItemSchema
Planning Center path /services/v2/service_types/{service_type_id}/plans/{plan_id}/items
Planning Center docs Item

How to reach it

Client path Returns Filters Create
pco.services.series.id(seriesId).plans.id(planId).live.id(liveId).items Collection No
pco.services.series.id(seriesId).plans.id(planId).items Collection Yes
pco.services.service_types.id(serviceTypeId).plan_templates.id(planTemplateId).items Collection Yes
pco.services.songs.id(songId).last_scheduled_item Collection No

From a collection, .id(itemId) addresses one Item: pco.services.songs.id(songId).last_scheduled_item.id(itemId). Collections support where, include, order, and pagination; single resources have get().

Attributes

On Services.ItemAttributes. Every resource also has id and type ('Item') next to its attributes.

Name Type Description
created_at string | null
custom_arrangement_sequence unknown[] | null See details.
custom_arrangement_sequence_full unknown[] | null
custom_arrangement_sequence_short unknown[] | null
description string | null
html_details string | null
item_type string | null See details.
key_name string | null
length number | null
sequence number | null
service_position string | null See details.
title string | null
updated_at string | null

Attribute details

custom_arrangement_sequence

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

[‘Verse 1’, ‘Chorus 1’, ‘Verse 2’]

item_type

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.

service_position

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

Relationships and includes

Side-load with include() (or get({ include })) and read with related(resource, name): arrangement, item_assignments, item_notes, item_times, key, media, selected_attachment, song.

Relationship Type To Includable
arrangement To one Arrangement Yes
key To one Key Yes
plan To one Plan No
selected_background To one Attachment No
selected_layout To one Layout No
song To one Song Yes

Querying

No documented where fields.

No documented order fields.

Edges

Follow these from one Item, ref = pco.services.songs.id(songId).last_scheduled_item.id(itemId):

Edge Leads to Returns Filters Create
ref.arrangement Arrangement Collection No
ref.attachments Attachment Collection Yes
ref.custom_slides CustomSlide Collection Yes
ref.item_assignments ItemAssignment Collection Yes
ref.item_notes ItemNote Collection Yes
ref.item_times ItemTime Collection No
ref.key Key Collection No
ref.media Media Collection No
ref.selected_attachment Attachment Collection No
ref.selected_background Attachment Collection No
ref.song Song Collection No

Writing

Property Value
Create Yes, create() on items on Plan, items on PlanTemplate
Update Yes, update() on a reference
Delete Yes, delete() on a reference

Create attributes

Typed as Services.ItemSchema['create'].

Attribute Type
arrangement_id string
copy_item_id string
custom_arrangement_sequence unknown[] | null
description string | null
html_details string | null
item_type string | null
key_id string
length number | null
media_ids string[]
selected_attachment_id string
selected_background_id string
selected_layout_id string
sequence number | null
service_position string | null
song_id string
title string | null

Update attributes

Typed as Services.ItemSchema['update'].

Attribute Type
arrangement_id string
custom_arrangement_sequence unknown[] | null
description string | null
html_details string | null
key_id string
length number | null
media_ids string[]
selected_attachment_id string
selected_background_id string
selected_layout_id string
service_position string | null
song_id string
title string | null

See Writing data.

Example

import type { Services } from '@mackenly/planningcenterkit';

const songId = '1'; // Song id

const page = await pco.services.songs.id(songId).last_scheduled_item.perPage(25).list();
const items: Services.Item[] = page.data;

Type to search…

↑↓ navigate↵ selectEsc close