---
title: "Create a Label"
method: POST
path: "/shop/organisations/{organisationId}/labels"
tags: ["Organisations"]
---

# Create a Label

`POST /shop/organisations/{organisationId}/labels`

Create a new label against the given organisation. Labels can be
restricted to a subset of the organisation's sites by passing the
relevant `site_ids`; staff at other sites won't see the label in
the admin UI.

## Path parameters

- `organisationId` string, uuid, required

## Request body

- object
  - `name` string, required — Display name of the label. 1-40 characters; must not contain HTML.
  - `color` string, nullable — Hex colour used to render the label in the admin UI, including the leading `#`. Lower-case hexadecimal; must match `#rrggbb`. Defaults to `#f1f1f1` when omitted.
  - `site_ids` string[], required — Identifiers of the sites within the organisation that should be allowed to see and apply this label. Every site ID must belong to the same organisation as the label.

## Response `201`

The label was successfully retrieved.

- object
  - `data` OrganisationLabel, required — A coloured label that can be attached to records (e.g. customers, bookings, orders) to highlight or categorise them in the admin UI. Labels belong to a single organisation and can optionally be restricted to a subset of the organisation's sites — staff only see labels whose `site_ids` intersect with the site they are working against.
    - `id` string, uuid, required — The unique identifier of the label.
    - `name` string, required — Display name of the label, shown next to the records it is attached to in the admin UI. 1-40 characters; must not contain HTML.
    - `color` string, required — Hex colour used to render the label in the admin UI, including the leading `#`. Lower-case hexadecimal; must match `#rrggbb`. When unset on create, defaults to `#f1f1f1`.
    - `organisation_id` string, uuid, required — Identifier of the organisation that owns the label. Every label is scoped to exactly one organisation.
    - `site_ids` string[], required — Identifiers of the sites within the organisation that can see and apply this label. Empty array means the label is visible to every site under the organisation.

## Other responses

- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `404` — The resource couldn't be found
- `422` — The request didn't pass validation

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)