---
title: "Arrangement (Services)"
description: "Each arrangement belongs to a song and is a different version of that song."
---

> Documentation Index
> Fetch the complete documentation index at: https://planningcenterkit.mackenly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Arrangement (Services)

Each arrangement belongs to a song and is a different version of that song.

| Property | Value |
| --- | --- |
| Product | [Services](/reference/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](https://api.planningcenteronline.com/docs/apps/services/versions/2018-11-01/vertices/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](/guides/querying/); 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-font-size). |
| `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](#meter). |
| `name` | `string \| null` |  |
| `notes` | `string \| null` |  |
| `number_chart_enabled` | `boolean \| null` |  |
| `numeral_chart_enabled` | `boolean \| null` |  |
| `print_margin` | `string \| null` | See [details](#print-margin). |
| `print_orientation` | `string \| null` | See [details](#print-orientation). |
| `print_page_size` | `string \| null` | See [details](#print-page-size). |
| `sequence` | `unknown[] \| null` | See [details](#sequence). |
| `sequence_full` | `unknown[] \| null` |  |
| `sequence_short` | `unknown[] \| null` |  |
| `updated_at` | `string \| null` |  |

### Attribute details

#### `chord_chart_font_size` {#chord-chart-font-size}

Possible Values:

`10`, `11`, `12`, `13`, `14`, `15`, `16`, `18`, `20`, `22`, `24`, `26`, `28`, `32`, `36`, `42`, `48`

#### `meter` {#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` {#print-margin}

Possible Values:

- `0.0in`

- `0.25in`

- `0.5in`

- `0.75in`

- `1.0in`

#### `print_orientation` {#print-orientation}

Possible Values:

- `Portrait`

- `Landscape`

#### `print_page_size` {#print-page-size}

Possible Values:

- `Widescreen (16x9)`

- `Fullscreen (4x3)`

- `A4`

- `Letter`

- `Legal`

- `11x17`

#### `sequence` {#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](/reference/services/person/) | No |
| `song` | To one | [Song](/reference/services/song/) | No |
| `updated_by` | To one | [Person](/reference/services/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](/reference/services/attachment/) | Collection |  | Yes |
| `ref.keys` | [Key](/reference/services/key/) | Collection |  | Yes |
| `ref.sections` | [ArrangementSections](/reference/services/arrangement-sections/) | Single resource |  | No |
| `ref.tags` | [Tag](/reference/services/tag/) | Collection |  | No |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `arrangements` on [Song](/reference/services/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](/guides/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

```ts
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;
```

Source: https://planningcenterkit.mackenly.com/reference/services/arrangement/index.mdx
