Skip to content
Docs
Open Backstage
Operation

Grant a customer tag

POST/customers/{customerId}/tags
Grants a defined tag to a customer, optionally with an expiry and metadata. The slug must name a definition that applies to customers (400 TAG_NOT_DEFINED, TAG_NOT_APPLICABLE, TAG_ARCHIVED) and lists the caller in grantableBy (403 TAG_NOT_GRANTABLE): `staff` for a person holding customertags.grant, `api` for an organisation API key or delegated token holding the customertags.write scope. Renewing: if the customer's previous grant of the tag has expired, it is closed (revokeReason `expired`) and a new grant is made (201, a new id, `customer.tag_granted`). If the customer holds the tag and it has not expired, a later `expiresAt` - or none, for a grant that no longer expires - extends that grant in place (200, the same id, recorded under `extensions`, `customer.tag_extended`); the same checks apply as to a grant. A grant that would change nothing - the held grant never expires, or already lasts as long or longer - is 409 CUSTOMER_TAG_ALREADY_GRANTED. A grant never shortens one: revoke it and grant again.

Path parameters

customerIdstringRequired
Customer ID

Headers

Idempotency-KeystringOptional
Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.

Body

tag*stringThe slug of a defined customer tag. An undefined slug is 400 TAG_NOT_DEFINED
source"manual" | "membership" | "import"
expiresAtstring,null (date-time)
metadataobject

Returns

The customer held the tag, unexpired; the grant was extended to the later expiry

Errors

400
Bad Request - Invalid input
401
Unauthorized - Authentication required
403
Forbidden - Insufficient permissions
404
Not Found - Resource not found
409
The customer already holds this tag until at least the requested expiry, or with no expiry (CUSTOMER_TAG_ALREADY_GRANTED)
500
Internal Server Error

Every error names its code and links to it. All error codes

curl -X POST "https://api.ticketlayer.com/v1/customers/cus_abc123/tags" \  -H "Authorization: Bearer tlak_..." \  -H "X-Ticketlayer-Org: your-org-slug" \  -H "Content-Type: application/json" \  -d '{    "tag": "member",    "source": "manual",    "expiresAt": "2026-06-13T10:00:00Z",    "metadata": {}  }'
Response 200
{
  "customerTag": {
    "id": "cent_abc123",
    "customerId": "cus_abc123",
    "tag": "member",
    "tagDefinitionId": "tgd_abc123",
    "source": "manual",
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "revokedAt": null,
    "revokedBy": null,
    "revokeReason": null,
    "grantedBy": "usr_abc123",
    "metadata": {},
    "extensions": [
      {
        "previousExpiresAt": "2026-09-30T23:59:59.000Z",
        "expiresAt": "2027-09-30T23:59:59.000Z",
        "extendedAt": "2026-09-20T10:30:00.000Z",
        "extendedBy": "client:oak_abc123",
        "source": "membership",
        "metadata": {
          "membershipId": "mem_2027"
        }
      }
    ],
    "createdAt": "2026-09-24T10:30:00.000Z",
    "updatedAt": "2026-09-24T10:30:00.000Z"
  }
}

Try it in test mode

Path parameters
Customer ID
Body
The slug of a defined customer tag. An undefined slug is 400 TAG_NOT_DEFINED