---
title: "List tiers"
method: GET
path: "/v2/loyalties/tier-structures/{tierStructureId}/tiers"
tags: ["Tier Structures"]
---

# List tiers

`GET /v2/loyalties/tier-structures/{tierStructureId}/tiers`

<Warning>

<Badge color="yellow">BETA endpoint</Badge>

This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.

</Warning>

Returns a cursor-paginated list of tiers belonging to the tier structure. This
endpoint does not support a `filters` parameter. The same field cannot be requested
in both ascending and descending order at once. Default order is `-created_at`.

## Path parameters

- `id` string, required

## Query parameters

- `limit` integer
- `order` union
  - 'created_at' | '-created_at' | 'name' | '-name'
  - string[]
- `cursor` string

## Response `200`

Paginated list of tiers.

- TierListResponse — Cursor-paginated list of tiers.
  - `data` Tier[], required — Tiers on the current page.
    - `id` string, required — Unique tier identifier.
    - `tier_structure_id` string, required — Identifier of the parent tier structure.
    - `name` string, required — Display name of the tier.
    - `qualification_rules` TierQualificationRules — Tier qualification rules.
      - `type` 'POINTS' | 'POINTS_AND_SEGMENT' — Qualification model.
      - `points` TierQualificationRulesPoints — Point thresholds for tier qualification.
        - `min_value` number — Minimum number of points required to qualify for the tier.
        - `max_value` number — Optional upper bound of points for the tier. Omitted when not set.
      - `segment` TierQualificationRulesSegment — Customer segment reference.
        - `id` string — Identifier of the customer segment.
    - `downgrade` TierDowngrade, required — Tier-level downgrade behavior.
      - `type` 'INHERIT' | 'NO_DOWNGRADE' — Downgrade model. Omitted when the tier has no downgrade configured.
    - `metadata` object, required — Free-form key/value object holding custom attributes. Defaults to `{}`.
    - `created_at` string, date-time, required — Creation timestamp (ISO 8601).
    - `updated_at` string, date-time, nullable, required — Last update timestamp (ISO 8601), or null if never updated.
    - `object` 'tier', required — Object type discriminator. Always `tier`.
  - `cursor` object, nullable, required — Pagination cursor for fetching the next page, or null when there are no more results.
    - `next` string — Cursor id to pass as the `cursor` query parameter for the next page.
    - `expires_at` string, date-time — Timestamp after which the cursor expires (ISO 8601).
  - `object` 'list', required — Object type discriminator. Always `list`.

## Other responses

- `400` — Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state.
- `404` — Resource not found.
- `409` — Conflict - e.g. duplicate resource or invalid state transition.
- `500` — Internal server error.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/versions/f6f2f3388362/schema)