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;