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

# List tiers

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

<Info>

<Badge color="gray">Documentation in progress</Badge>

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

</Info>

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 — Unique 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 — Unique 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/revisions/69be73b5cff0/schema)