Tags

A tag is a short, stable label, such as member or student, that the rest of the platform refers to by its slug. Tags do two jobs:

• Customer tags say who a buyer is. A ticket type can require one (a members' price), and a sale window can be open only to holders of one (a members' priority booking). They are lasting and belong to the customer, not to a channel: a member is a member on the website, in the box office and on a partner's site.
• Descriptive tags say what something is: an event (family), a venue (accessible), a ticket type (concession) or a price (early-bird). Ticket-type and price tags are what an offer's fee rules match on, which is why the offers engine reads them.

Every tag an organisation uses is defined once. The definition fixes the slug, gives it a label a buyer reads, and says what it may be applied to and who may grant it.

Tag definitions#

/v1/tag-definitions holds them. @ticketlayer/backstage has the same operations as client.tags.list(), create(), get(), update() and archive().

curl -X POST https://api.ticketlayer.com/v1/tag-definitions \
  -H "Authorization: Bearer <staff token>" \
  -H "X-Ticketlayer-Org: your-org-slug" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "member",
    "label": "Members",
    "description": "Current club members, renewed each season",
    "kind": "customer",
    "grantableBy": ["staff", "api"]
  }'

Defining and editing tags needs tags.write over every account in the organisation; reading them needs tags.read. An organisation API key can hold the tags.read and tags.write scopes.

Archiving (DELETE /v1/tag-definitions/{id}, or PATCH with archived: true) deletes nothing. The slug stays reserved, every reference keeps working and customers keep the tag, but it can no longer be granted. PATCH with archived: false restores it. Archived definitions are left out of the list unless you pass includeArchived=true.

Who may grant a customer tag#

grantableBy lists who may give the tag to a customer:

Adding api to a definition needs a person, not a key: a key that tries is refused with 403 TAG_API_GRANTING_NEEDS_STAFF. That keeps a key from widening what keys may grant.

Customer tags#

A customer's tags are at /v1/customers/{customerId}/tags (client.customers.listTags(), grantTag() and revokeTag()).

curl -X POST https://api.ticketlayer.com/v1/customers/cus_01J.../tags \
  -H "Authorization: Bearer tlak_..." \
  -H "X-Ticketlayer-Org: your-org-slug" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "member", "source": "membership", "expiresAt": "2027-08-31T23:59:59Z" }'

A grant names the tag by slug, and may carry an expiresAt and metadata. It is refused when:

• the slug has no definition: 400 TAG_NOT_DEFINED;
• the definition does not apply to customers: 400 TAG_NOT_APPLICABLE;
• the definition is archived: 400 TAG_ARCHIVED;
• the caller is not in grantableBy: 403 TAG_NOT_GRANTABLE;
• the customer already holds it: 409 CUSTOMER_TAG_ALREADY_GRANTED.

Each grant records its source: manual (staff or an API key), membership, import, or presale for a grant made by redeeming a presale code.

Revoking (POST /v1/customers/{customerId}/tags/{customerTagId}/revoke) keeps the grant and marks it revoked. A person holding customertags.revoke may revoke any tag; a key may revoke only a tag whose definition lists api. The list leaves revoked grants out unless you pass includeRevoked=true.

A grant whose expiresAt has passed stops applying on its own.

What a customer tag admits#

A tag a customer holds, and has not had revoked or seen expire, is read server-side wherever that customer buys. A request never asserts one.

• Gated ticket types. A ticket type that requires a tag is offered only to a customer who holds it. See Offers that need a tag.
• Sale windows. A listing rule's window can name audienceTags; any of them admits the customer to that window, and an empty list is everyone. This is how a members' priority booking opens a week before general sale.

Webhooks#

customer.tag_granted and customer.tag_revoked tell your system when a customer gains or loses a tag, including when a presale code grants one and when a grant expires (reason: expired). They are described in Webhooks.

Benefits are customer tags#

Customer tags were called benefits. The benefits routes have gone; each one's tags route acts on the same grants:

In the same way, a listing rule window's audience (one slug) is deprecated in favour of audienceTags (a list), and a ticket type's requiredBenefit holds the slug of the customer tag it requires.

The operations are in the API reference under Tags and Customers.