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

# List tiers

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

## Request

- Base URL: `https://api.voucherify.io`
- URL: `https://api.voucherify.io/v2/loyalties/tier-structures/{tierStructureId}/tiers`
- Auth: one of:
  - API key in header `X-App-Id` and API key in header `X-App-Token`
  - HTTP bearer

<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`.

## Query parameters

- `limit` union
  - number
  - string
- `order` union
  - 'created_at' | '-created_at' | 'name' | '-name'
  - string[]
- `cursor` string, nullable

## Response `200`

Paginated list of tiers.

- V2LoyaltiesTierStructuresTiersListResponseBody: Cursor-paginated list of tiers.
  - `data` Tier[], required: Tiers on the current page.
    - `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.
    - `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` LoyaltyV2ActivityTierQualificationRulesPoints: 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` LoyaltyV2ActivityTierQualificationRulesSegment: Customer segment reference.
        - `id` string: Unique identifier of the customer segment.
    - `downgrade` LoyaltyV2ActivityTierDowngrade, required: Tier-level downgrade behavior.
      - `type` 'INHERIT' | 'NO_DOWNGRADE': Downgrade model. Omitted when the tier has no downgrade configured.
    - `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.
- `500`: Internal server error.

## Changes

- **2026-10-14** (v2) `d29b33490051`: 9 breaking, 1 warning, 1 info
  - the `allOf[#/components/schemas/TierListResponse]/data/items/` response's property type changed from `object` to no type for status `200`
  - removed the required property `allOf[#/components/schemas/TierListResponse]/data/items/created_at` from the response with the `200` status
  - removed the required property `allOf[#/components/schemas/TierListResponse]/data/items/downgrade` from the response with the `200` status
  - removed the required property `allOf[#/components/schemas/TierListResponse]/data/items/id` from the response with the `200` status
  - …7 more
- **2026-10-14** (v2) `be14b3318eb3`: 1 breaking, 10 info
  - the `allOf[#/components/schemas/TierListResponse]/data/items/` response's property type changed from no type to `object` for status `200`
  - added the optional property `allOf[#/components/schemas/TierListResponse]/data/items/qualification_rules` to the response with the `200` status
  - removed `#/components/schemas/TierMetadataBase, subschema #2` from the `allOf[#/components/schemas/TierListResponse]/data/items/` response property `allOf` list for the response status `200`
  - added the required property `allOf[#/components/schemas/TierListResponse]/data/items/created_at` to the response with the `200` status
  - …7 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/tier-structures/:tierStructureId/tiers/get.md)

---

[API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)