---
title: "Tag (Calendar)"
description: "An organizational tag that can be applied to events."
---

> 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.

# Tag (Calendar)

An organizational tag that can be applied to events.

Applied tags can be used to filter events on the calendar or
filter events for reports, iCal feeds, kiosk, and the widget.

| Property | Value |
| --- | --- |
| Product | [Calendar](/reference/calendar/) (`pco.calendar`, API version `2026-06-22`) |
| Resource type | `Tag` |
| TypeScript | `Calendar.Tag`, attributes `Calendar.TagAttributes`, schema `Calendar.TagSchema` |
| Planning Center path | `/calendar/v2/tags` |
| Planning Center docs | [Tag](https://api.planningcenteronline.com/docs/apps/calendar/versions/2026-06-22/vertices/tag) |

## How to reach it

| Client path | Returns | Filters | Create |
| --- | --- | --- | --- |
| `pco.calendar.tags` | Collection | `individual` | Yes |
| `pco.calendar.events.id(eventId).tags` | Collection |  | No |
| `pco.calendar.event_instances.id(eventInstanceId).tags` | Collection |  | No |
| `pco.calendar.tag_groups.id(tagGroupId).tags` | Collection |  | No |

From a collection, `.id(tagId)` addresses one Tag: `pco.calendar.tags.id(tagId)`. Collections support [`where`, `include`, `order`, and pagination](/guides/querying/); single resources have `get()`.

## Attributes

On `Calendar.TagAttributes`. Every resource also has `id` and `type` (`'Tag'`) next to its attributes.

| Name | Type | Description |
| --- | --- | --- |
| `church_center_category` | `boolean \| null` | `true` indicates that this tag is used as a category on Church Center |
| `color` | `string \| null` | Hex color code of the tag |
| `created_at` | `string \| null` | UTC time at which the tag was created |
| `name` | `string \| null` | The tag name |
| `position` | `number \| null` | See [details](#position). |
| `updated_at` | `string \| null` | UTC time at which the tag was updated |

### Attribute details

#### `position` {#position}

If the tag belongs to a TagGroup,
position indicates place in list within TagGroup in the UI.

If the tag does not belong to a TagGroup,
position indicates place in list under "Individual Tags" in the UI.

## Relationships and includes

Side-load with `include()` (or `get({ include })`) and read with `related(resource, name)`: `tag_group`.

## Querying

### Where

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

| Field | Value type | Operators |
| --- | --- | --- |
| `church_center_category` | `boolean` | Equality only |
| `color` | `string` | Equality only |
| `created_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |
| `id` | `string` | Equality only |
| `name` | `string` | Equality only |
| `position` | `number` | Equality only |
| `updated_at` | `string \| Date` | `gt`, `gte`, `lt`, `lte` |

### Order

`order(...)` accepts these fields, ascending, or descending with a `-` prefix: `name`, `position`.

### Filters

`filter(...)` names depend on the edge you query through:

| Edge | Filters |
| --- | --- |
| `pco.calendar.tags` | `individual` |

## Edges

Follow these from one Tag, `ref = pco.calendar.tags.id(tagId)`:

| Edge | Leads to | Returns | Filters | Create |
| --- | --- | --- | --- | --- |
| `ref.event_instances` | [EventInstance](/reference/calendar/event-instance/) | Collection | `canceled`, `not_canceled` | No |
| `ref.events` | [Event](/reference/calendar/event/) | Collection |  | No |
| `ref.tag_group` | [TagGroup](/reference/calendar/tag-group/) | Collection |  | No |

## Writing

| Property | Value |
| --- | --- |
| Create | Yes, `create()` on `pco.calendar.tags` |
| Update | Yes, `update()` on a reference |
| Delete | Yes, `delete()` on a reference |

### Create attributes

Typed as `Calendar.TagSchema['create']`.

| Attribute | Type |
| --- | --- |
| `church_center_category` | `boolean \| null` |
| `color` | `string \| null` |
| `events_ids` | `string[]` |
| `name` | `string \| null` |
| `position` | `number \| null` |
| `tag_group_id` | `string` |

### Update attributes

Typed as `Calendar.TagSchema['update']`.

| Attribute | Type |
| --- | --- |
| `church_center_category` | `boolean \| null` |
| `color` | `string \| null` |
| `events_ids` | `string[]` |
| `name` | `string \| null` |
| `position` | `number \| null` |
| `tag_group_id` | `string` |

See [Writing data](/guides/writing-data/).

## Example

```ts
import type { Calendar } from '@mackenly/planningcenterkit';

const page = await pco.calendar.tags.order('name').perPage(25).list();
const items: Calendar.Tag[] = page.data;
```

Source: https://planningcenterkit.mackenly.com/reference/calendar/tag/index.mdx
