Skip to content

Song (Services)

A song

A song

Property Value
Product Services (pco.services, API version 2018-11-01)
Resource type Song
TypeScript Services.Song, attributes Services.SongAttributes, schema Services.SongSchema
Planning Center path /services/v2/songs
Planning Center docs Song

How to reach it

Client path Returns Filters Create
pco.services.songs Collection Yes
pco.services.songs.id(songId).last_scheduled_item.id(itemId).song Collection No

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

Attributes

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

Name Type Description
admin string | null
author string | null
ccli_number number | null
copyright string | null
created_at string | null
hidden boolean | null
last_scheduled_at string | null
last_scheduled_short_dates string | null
notes string | null
themes string | null
title string | null See details.
updated_at string | null

Attribute details

title

The name of the song.

When setting this value on a create you can pass a CCLI number and Services will fetch the song metadata for you.

Querying

Where

where(field, value) for equality; where(field, op, value) with the operators listed.

Field Value type Operators
author string Equality only
ccli_number number Equality only
hidden boolean Equality only
themes string Equality only
title string Equality only

Order

order(...) accepts these fields, ascending, or descending with a - prefix: created_at, last_scheduled_at, title, updated_at.

Edges

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

Edge Leads to Returns Filters Create
ref.arrangements Arrangement Collection Yes
ref.attachments Attachment Collection Yes
ref.last_scheduled_item Item Collection No
ref.song_schedules SongSchedule Collection after, before, most_recent, most_recent_with_upcoming, three_most_recent No
ref.tags Tag Collection No
ref.unscoped_arrangements Arrangement Collection No

Writing

Property Value
Create Yes, create() on pco.services.songs
Update Yes, update() on a reference
Delete Yes, delete() on a reference

Create attributes

Typed as Services.SongSchema['create'].

Attribute Type
admin string | null
author string | null
ccli_number number | null
copyright string | null
hidden boolean | null
import_ccli_chord_chart unknown
import_ccli_chord_pro unknown
import_ccli_lyrics unknown
themes string | null
title string | null

Update attributes

Typed as Services.SongSchema['update'].

Attribute Type
admin string | null
author string | null
ccli_number number | null
copyright string | null
hidden boolean | null
themes string | null
title string | null

See Writing data.

Actions

Run with ref.action(name, body?). Bodies are untyped: see Planning Center’s docs for each action.

Action Path Description
assign_tags POST /services/v2/songs/{song_id}/assign_tags Used to assign tags to a song.

Example

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

const page = await pco.services.songs.order('created_at').perPage(25).list();
const items: Services.Song[] = page.data;

Type to search…

↑↓ navigate↵ selectEsc close