Each arrangement belongs to a song and is a different version of that song.
| Property | Value |
|---|---|
| Product | Services (pco.services, API version 2018-11-01) |
| Resource type | Arrangement |
| TypeScript | Services.Arrangement, attributes Services.ArrangementAttributes, schema Services.ArrangementSchema |
| Planning Center path | /services/v2/songs/{song_id}/arrangements |
| Planning Center docs | Arrangement |
How to reach it
| Client path | Returns | Filters | Create |
|---|---|---|---|
pco.services.songs.id(songId).last_scheduled_item.id(itemId).arrangement |
Collection | No | |
pco.services.songs.id(songId).arrangements |
Collection | Yes | |
pco.services.songs.id(songId).unscoped_arrangements |
Collection | No |
From a collection, .id(arrangementId) addresses one Arrangement: pco.services.songs.id(songId).arrangements.id(arrangementId). Collections support where, include, order, and pagination; single resources have get().
Attributes
On Services.ArrangementAttributes. Every resource also has id and type ('Arrangement') next to its attributes.
| Name | Type | Description |
|---|---|---|
archived_at |
string | null |
|
bpm |
number | null |
|
chord_chart |
string | null |
A string of lyrics and chords. Supports standard and ChordPro formats. |
chord_chart_chord_color |
number | null |
|
chord_chart_columns |
number | null |
|
chord_chart_font |
string | null |
|
chord_chart_font_size |
number | null |
See details. |
chord_chart_key |
string | null |
|
created_at |
string | null |
|
has_chord_chart |
boolean | null |
|
has_chords |
boolean | null |
|
length |
number | null |
|
lyrics |
string | null |
|
lyrics_enabled |
boolean | null |
|
meter |
string | null |
See details. |
name |
string | null |
|
notes |
string | null |
|
number_chart_enabled |
boolean | null |
|
numeral_chart_enabled |
boolean | null |
|
print_margin |
string | null |
See details. |
print_orientation |
string | null |
See details. |
print_page_size |
string | null |
See details. |
sequence |
unknown[] | null |
See details. |
sequence_full |
unknown[] | null |
|
sequence_short |
unknown[] | null |
|
updated_at |
string | null |
Attribute details
chord_chart_font_size
Possible Values:
10, 11, 12, 13, 14, 15, 16, 18, 20, 22, 24, 26, 28, 32, 36, 42, 48
meter
Possible Values:
-
2/2 -
2/4 -
3/2 -
3/4 -
4/2 -
4/4 -
5/4 -
6/4 -
3/8 -
6/8 -
7/4 -
7/8 -
9/8 -
12/4 -
12/8
print_margin
Possible Values:
-
0.0in -
0.25in -
0.5in -
0.75in -
1.0in
print_orientation
Possible Values:
-
Portrait -
Landscape
print_page_size
Possible Values:
-
Widescreen (16x9) -
Fullscreen (4x3) -
A4 -
Letter -
Legal -
11x17
sequence
An array of strings containing a label and a number describing the section:
[‘Verse 1’, ‘Chorus 1’, ‘Verse 2’]
Relationships and includes
Side-load with include() (or get({ include })) and read with related(resource, name): keys, sections.
| Relationship | Type | To | Includable |
|---|---|---|---|
created_by |
To one | Person | No |
song |
To one | Song | No |
updated_by |
To one | Person | No |
Querying
No documented where fields.
Order
order(...) accepts these fields, ascending, or descending with a - prefix: name.
Edges
Follow these from one Arrangement, ref = pco.services.songs.id(songId).arrangements.id(arrangementId):
| Edge | Leads to | Returns | Filters | Create |
|---|---|---|---|---|
ref.attachments |
Attachment | Collection | Yes | |
ref.keys |
Key | Collection | Yes | |
ref.sections |
ArrangementSections | Single resource | No | |
ref.tags |
Tag | Collection | No |
Writing
| Property | Value |
|---|---|
| Create | Yes, create() on arrangements on Song |
| Update | Yes, update() on a reference |
| Delete | Yes, delete() on a reference |
Create attributes
Typed as Services.ArrangementSchema['create'].
| Attribute | Type |
|---|---|
bpm |
number | null |
chord_chart |
string | null |
chord_chart_chord_color |
number | null |
chord_chart_columns |
number | null |
chord_chart_font |
string | null |
chord_chart_font_size |
number | null |
chord_chart_key |
string | null |
import_ccli_chord_chart |
unknown |
import_ccli_chord_pro |
unknown |
import_ccli_lyrics |
unknown |
import_chart_pro |
unknown |
import_chart_pro_options |
unknown |
import_rehearsal_mix |
unknown |
import_rehearsal_mix_options |
unknown |
import_rehearsal_pack |
unknown |
import_rehearsal_pack_options |
unknown |
isrc |
unknown |
length |
number | null |
lyrics_enabled |
boolean | null |
meter |
string | null |
mtid |
unknown |
name |
string | null |
notes |
string | null |
number_chart_enabled |
boolean | null |
numeral_chart_enabled |
boolean | null |
print_margin |
string | null |
print_orientation |
string | null |
print_page_size |
string | null |
rehearsal_mix_id |
string |
rehearsal_mix_thumbnail |
unknown |
sequence |
unknown[] | null |
Update attributes
Typed as Services.ArrangementSchema['update'].
| Attribute | Type |
|---|---|
bpm |
number | null |
chord_chart |
string | null |
chord_chart_chord_color |
number | null |
chord_chart_columns |
number | null |
chord_chart_font |
string | null |
chord_chart_font_size |
number | null |
chord_chart_key |
string | null |
import_chart_pro |
unknown |
import_chart_pro_options |
unknown |
import_rehearsal_mix |
unknown |
import_rehearsal_mix_options |
unknown |
import_rehearsal_pack |
unknown |
import_rehearsal_pack_options |
unknown |
isrc |
unknown |
length |
number | null |
lyrics_enabled |
boolean | null |
meter |
string | null |
mtid |
unknown |
name |
string | null |
notes |
string | null |
number_chart_enabled |
boolean | null |
numeral_chart_enabled |
boolean | null |
print_margin |
string | null |
print_orientation |
string | null |
print_page_size |
string | null |
rehearsal_mix_id |
string |
rehearsal_mix_thumbnail |
unknown |
sequence |
unknown[] | 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 |
|---|---|---|
archive |
POST /services/v2/songs/{song_id}/arrangements/{arrangement_id}/archive |
|
assign_tags |
POST /services/v2/songs/{song_id}/arrangements/{arrangement_id}/assign_tags |
Used to assign tags to an arrangement. |
unarchive |
POST /services/v2/songs/{song_id}/arrangements/{arrangement_id}/unarchive |
Restore an archived Arrangement. Must use the unscoped_arrangements endpoint. |
Example
import type { Services } from '@mackenly/planningcenterkit';
const songId = '1'; // Song id
const page = await pco.services.songs.id(songId).arrangements.order('name').perPage(25).list();
const items: Services.Arrangement[] = page.data;