> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # List tiers > ⚠️ **BETA endpoint** 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 or your Technical Account Manager. 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`. ## OpenAPI ````yaml /openapi/loyalties-v2.json get /v2/loyalties/tier-structures/{tierStructureId}/tiers openapi: 3.1.0 info: title: Voucherify Loyalty v2 API version: 2.0.0 description: >- Complete OpenAPI specification for the Voucherify Loyalty v2 API. All endpoints require the LOYALTY_V2 feature flag. Combined from per-domain specs: programs.yaml, members.yaml, program-operations.yaml, card-definitions.yaml, earning-rules.yaml, tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml servers: - url: '{protocol}://{host}' variables: protocol: default: https enum: - https - http host: default: api.voucherify.io security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - name: Programs description: >- Loyalty program CRUD, lifecycle management, program-scoped resource assignments (card definitions, earning rules, rewards, tier structures), member management (create, list, get, activate, deactivate, delete), card operations (points adjustment, pending points, expiring points, transactions), reward purchases, and activity history. - name: Card Definitions description: >- CRUD operations, lifecycle management, and activity history for card definitions. Card definitions describe the configuration for loyalty cards, including code generation, points expiration, earning/spending limits, pending points, refunds, and balance settings. - name: Earning Rules description: >- Manage earning rules that define how customers earn points or receive incentives based on triggers (events, segments, custom events). Includes CRUD, lifecycle, and activity history. - name: Tier Structures description: >- CRUD operations, lifecycle management, and activity history for tier structures. Includes nested tier definitions (create, list, update, delete) within tier structures. Tier structures define the tiering model for loyalty programs — how members qualify for and move between tiers. - name: Benefits description: >- Manage benefit definitions (fixed points, proportional points, material, digital). Includes CRUD, lifecycle transitions, and activity history. - name: Rewards description: >- CRUD, lifecycle operations, and activity history for reward definitions. Rewards can be material (product/SKU) or digital (discount coupons, gift vouchers). - name: Examine description: >- Evaluation endpoints that estimate earning opportunities and reward availability for a customer across their loyalty program memberships, without side effects. paths: /v2/loyalties/tier-structures/{tierStructureId}/tiers: get: tags: - Tier Structures summary: List tiers description: > ⚠️ **BETA endpoint** 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 or your Technical Account Manager. 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`. operationId: listTiers parameters: - name: id in: path required: true description: Unique tier structure identifier. schema: type: string pattern: ^lts_[a-f0-9]+$ - name: limit in: query required: false description: > Maximum number of items returned per page. An integer between 1 and 100. Defaults to 10. schema: type: integer minimum: 1 maximum: 100 default: 10 - name: order in: query required: false description: > Sort order. A single field name or an array of field names; prefix a field with `-` for descending order. Default is `-created_at`. The same field must not be requested in both ascending and descending direction at once. schema: oneOf: - type: string enum: - created_at - '-created_at' - name - '-name' - type: array items: type: string enum: - created_at - '-created_at' - name - '-name' - name: cursor in: query required: false description: > Pagination cursor returned in the `cursor.next` field of a previous response. Must match the tiers cursor id format. schema: type: string pattern: ^lcrst_[a-f0-9]+$ responses: '200': description: Paginated list of tiers. content: application/json: schema: $ref: '#/components/schemas/TierListResponse' '400': description: >- Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: Conflict - e.g. duplicate resource or invalid state transition. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: TierListResponse: type: object description: Cursor-paginated list of tiers. properties: data: type: array description: Tiers on the current page. items: $ref: '#/components/schemas/Tier' cursor: description: > Pagination cursor for fetching the next page, or null when there are no more results. oneOf: - type: object properties: next: type: string pattern: ^lcrst_[a-f0-9]+$ description: >- Cursor id to pass as the `cursor` query parameter for the next page. expires_at: type: string format: date-time description: Timestamp after which the cursor expires (ISO 8601). - type: 'null' object: type: string const: list description: Object type discriminator. Always `list`. required: - data - cursor - object ErrorResponse: type: object description: Standard error response returned by all Loyalty v2 endpoints. properties: code: type: integer description: HTTP status code of the error. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional details about the error. request_id: type: string description: Identifier of the request that produced the error. Tier: type: object description: Tier resource. properties: id: type: string pattern: ^lt_[a-f0-9]+$ description: Unique tier identifier. tier_structure_id: type: string pattern: ^lts_[a-f0-9]+$ description: Identifier of the parent tier structure. name: type: string description: Display name of the tier. qualification_rules: $ref: '#/components/schemas/TierQualificationRules' description: Rules determining which members qualify for this tier. downgrade: $ref: '#/components/schemas/TierDowngrade' description: > Tier-level downgrade behavior. Always present; when the tier has no downgrade configured, an empty object (no `type`) is returned. metadata: type: object description: >- Free-form key/value object holding custom attributes. Defaults to `{}`. created_at: type: string format: date-time description: Creation timestamp (ISO 8601). updated_at: type: - string - 'null' format: date-time description: Last update timestamp (ISO 8601), or null if never updated. object: type: string const: tier description: Object type discriminator. Always `tier`. required: - id - tier_structure_id - name - downgrade - metadata - created_at - updated_at - object TierQualificationRules: type: object description: Tier qualification rules. properties: type: type: string enum: - POINTS - POINTS_AND_SEGMENT description: Qualification model. points: $ref: '#/components/schemas/TierQualificationRulesPoints' description: Point thresholds for the tier. Omitted when not configured. segment: $ref: '#/components/schemas/TierQualificationRulesSegment' description: > Customer segment reference. Present only when `type` is `POINTS_AND_SEGMENT`. TierDowngrade: type: object description: Tier-level downgrade behavior. properties: type: type: string enum: - INHERIT - NO_DOWNGRADE description: | Downgrade model. Omitted when the tier has no downgrade configured. TierQualificationRulesPoints: type: object description: Point thresholds for tier qualification. properties: min_value: type: number description: Minimum number of points required to qualify for the tier. max_value: type: number description: Optional upper bound of points for the tier. Omitted when not set. TierQualificationRulesSegment: type: object description: Customer segment reference. properties: id: type: string description: Identifier of the customer segment. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````