> ## 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 tier structures > ⚠️ **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 tier structures. 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 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: get: tags: - Tier Structures summary: List tier structures 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 tier structures. The same field cannot be requested in both ascending and descending order at once. Default order is `-created_at`. operationId: listTierStructures parameters: - 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 - '-type' - status - '-status' - type: array items: type: string enum: - '-created_at' - created_at - name - '-name' - type - '-type' - status - '-status' - name: cursor in: query required: false description: > Pagination cursor returned in the `cursor.next` field of a previous response. Must match the tier structures cursor id format. schema: type: string pattern: ^lcrsts_[a-f0-9]+$ - name: filters in: query required: false style: deepObject explode: true description: | Field-specific filter conditions, passed as a deep object (e.g. `filters[status][conditions][$is]=ACTIVE`). schema: $ref: '#/components/schemas/TierStructureListFilters' responses: '200': description: Paginated list of tier structures. content: application/json: schema: $ref: '#/components/schemas/TierStructureListResponse' '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: TierStructureListFilters: type: object description: > Filters for the tier structures list. Each field accepts a `conditions` object; each filter field may also be null. properties: junction: description: >- Logical junction combining the field filters. Defaults to AND semantics. oneOf: - type: string enum: - AND - OR - type: 'null' id: description: >- Filter by tier structure id (ID field conditions, pattern `^lts_[a-f0-9]+$`). oneOf: - $ref: '#/components/schemas/TierStructureFilterIdField' - type: 'null' name: description: Filter by tier structure name (string field conditions). oneOf: - $ref: '#/components/schemas/TierStructureFilterStringField' - type: 'null' type: description: Filter by tier structure type (enum field conditions). oneOf: - $ref: '#/components/schemas/TierStructureFilterTypeField' - type: 'null' status: description: Filter by tier structure status (enum field conditions). oneOf: - $ref: '#/components/schemas/TierStructureFilterStatusField' - type: 'null' created_at: description: Filter by creation date (date field conditions). oneOf: - $ref: '#/components/schemas/TierStructureFilterDateField' - type: 'null' additionalProperties: false TierStructureListResponse: type: object description: Cursor-paginated list of tier structures. properties: data: type: array description: Tier structures on the current page. items: $ref: '#/components/schemas/TierStructure' 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: ^lcrsts_[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. TierStructureFilterIdField: type: object description: > ID field filter for tier structure ids. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Each condition accepts a single string or an array of strings matching `^lts_[a-f0-9]+$`. properties: conditions: type: object minProperties: 1 additionalProperties: false description: Condition operators applied to the field. properties: $is: description: Matches when the field equals the given id. oneOf: - type: string pattern: ^lts_[a-f0-9]+$ - type: array minItems: 1 maxItems: 1 items: type: string pattern: ^lts_[a-f0-9]+$ - type: 'null' $is_not: description: Matches when the field does not equal the given id. oneOf: - type: string pattern: ^lts_[a-f0-9]+$ - type: array minItems: 1 maxItems: 1 items: type: string pattern: ^lts_[a-f0-9]+$ - type: 'null' $in: description: Matches when the field equals any of the given ids (up to 100). oneOf: - type: string pattern: ^lts_[a-f0-9]+$ - type: array minItems: 1 maxItems: 100 items: type: string pattern: ^lts_[a-f0-9]+$ - type: 'null' $not_in: description: Matches when the field equals none of the given ids (up to 100). oneOf: - type: string pattern: ^lts_[a-f0-9]+$ - type: array minItems: 1 maxItems: 100 items: type: string pattern: ^lts_[a-f0-9]+$ - type: 'null' required: - conditions additionalProperties: false TierStructureFilterStringField: type: object description: > String field filter. Allowed conditions: `$is`, `$is_not`, `$contains`, `$not_contain`, `$starts_with`, `$ends_with`, `$in`, `$not_in`, `$has_value`, `$is_unknown`. Each condition accepts a single string or an array of strings. properties: conditions: type: object minProperties: 1 additionalProperties: false description: Condition operators applied to the field. properties: $is: description: Matches when the field equals the given value. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $is_not: description: Matches when the field does not equal the given value. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $contains: description: Matches when the field contains the given substring. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $not_contain: description: Matches when the field does not contain the given substring. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $starts_with: description: Matches when the field starts with the given prefix. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $ends_with: description: Matches when the field ends with the given suffix. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $in: description: >- Matches when the field equals any of the given values (up to 10). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 10 - type: 'null' $not_in: description: >- Matches when the field equals none of the given values (up to 10). oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 10 - type: 'null' $has_value: description: >- Matches when the field has any value. The value of this condition is ignored. oneOf: - type: string - type: array maxItems: 1 - type: 'null' $is_unknown: description: >- Matches when the field has no value. The value of this condition is ignored. oneOf: - type: string - type: array maxItems: 1 - type: 'null' required: - conditions additionalProperties: false TierStructureFilterTypeField: type: object description: > Enum field filter for tier structure `type`. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed values: `POINT_BALANCE`, `POINT_EARNED`. properties: conditions: type: object minProperties: 1 additionalProperties: false description: Condition operators applied to the field. properties: $is: description: Matches when the field equals the given value. oneOf: - type: string enum: - POINT_BALANCE - POINT_EARNED - type: array minItems: 1 maxItems: 1 items: type: string enum: - POINT_BALANCE - POINT_EARNED - type: 'null' $is_not: description: Matches when the field does not equal the given value. oneOf: - type: string enum: - POINT_BALANCE - POINT_EARNED - type: array minItems: 1 maxItems: 1 items: type: string enum: - POINT_BALANCE - POINT_EARNED - type: 'null' $in: description: >- Matches when the field equals any of the given values (up to 10). oneOf: - type: string enum: - POINT_BALANCE - POINT_EARNED - type: array minItems: 1 maxItems: 10 items: type: string enum: - POINT_BALANCE - POINT_EARNED - type: 'null' $not_in: description: >- Matches when the field equals none of the given values (up to 10). oneOf: - type: string enum: - POINT_BALANCE - POINT_EARNED - type: array minItems: 1 maxItems: 10 items: type: string enum: - POINT_BALANCE - POINT_EARNED - type: 'null' required: - conditions additionalProperties: false TierStructureFilterStatusField: type: object description: > Enum field filter for tier structure `status`. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed values: `DRAFT`, `ACTIVE`, `INACTIVE`, `DELETED`. properties: conditions: type: object minProperties: 1 additionalProperties: false description: Condition operators applied to the field. properties: $is: description: Matches when the field equals the given value. oneOf: - type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: array minItems: 1 maxItems: 1 items: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: 'null' $is_not: description: Matches when the field does not equal the given value. oneOf: - type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: array minItems: 1 maxItems: 1 items: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: 'null' $in: description: >- Matches when the field equals any of the given values (up to 10). oneOf: - type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: array minItems: 1 maxItems: 10 items: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: 'null' $not_in: description: >- Matches when the field equals none of the given values (up to 10). oneOf: - type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: array minItems: 1 maxItems: 10 items: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED - type: 'null' required: - conditions additionalProperties: false TierStructureFilterDateField: type: object description: > Date field filter. Allowed conditions: `$before`, `$after`, `$is`, `$more_than`, `$less_than`, `$has_value`, `$is_unknown`. `$before`/`$after` accept valid date strings; `$is`/`$more_than`/`$less_than` accept non-negative integer values. properties: conditions: type: object minProperties: 1 additionalProperties: false description: Condition operators applied to the field. properties: $before: description: >- Matches when the field is before the given date. Value must be a valid date string. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $after: description: >- Matches when the field is after the given date. Value must be a valid date string. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $is: description: | Matches by relative value. A non-negative integer. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $more_than: description: > Matches by relative value (greater than). A non-negative integer. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $less_than: description: | Matches by relative value (less than). A non-negative integer. oneOf: - type: string - type: array items: type: string minItems: 1 maxItems: 1 - type: 'null' $has_value: description: >- Matches when the field has any value. The value of this condition is ignored. oneOf: - type: string - type: array maxItems: 1 - type: 'null' $is_unknown: description: >- Matches when the field has no value. The value of this condition is ignored. oneOf: - type: string - type: array maxItems: 1 - type: 'null' required: - conditions additionalProperties: false TierStructure: type: object description: Tier structure resource. properties: id: type: string description: Unique tier structure identifier. pattern: ^lts_[a-f0-9]+$ name: type: string description: Display name of the tier structure. type: type: string enum: - POINT_BALANCE - POINT_EARNED description: Tier qualification tracking model. point_balance: $ref: '#/components/schemas/TierStructurePointBalance' description: > Point balance tracking settings. Present only when `type` is `POINT_BALANCE`; omitted otherwise. point_earned: $ref: '#/components/schemas/TierStructurePointEarned' description: > Points earned tracking settings. Present only when `type` is `POINT_EARNED`; omitted otherwise. expiration: $ref: '#/components/schemas/TierStructureExpiration' description: Tier membership expiration settings. downgrade: $ref: '#/components/schemas/TierStructureDowngrade' description: Downgrade behavior applied when tier membership expires. metadata: type: object description: >- Free-form key/value object holding custom attributes. Defaults to `{}`. status: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED description: Current lifecycle status of the tier structure. 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_structure description: Object type discriminator. Always `tier_structure`. required: - id - name - type - expiration - downgrade - metadata - status - created_at - updated_at - object TierStructurePointBalance: type: object description: Point balance tracking settings. properties: card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Identifier of the card definition whose point balance is tracked. TierStructurePointEarned: type: object description: Points earned tracking settings. properties: card_definition_id: type: string pattern: ^lcdef_[a-f0-9]+$ description: Identifier of the card definition whose earned points are tracked. period: $ref: '#/components/schemas/TierStructurePointEarnedPeriod' description: Tracking period during which earned points are accumulated. type: type: string enum: - IMMEDIATELY - NEXT_TRACKING_PERIOD description: When a tier change resulting from earned points takes effect. TierStructureExpiration: type: object description: > Tier membership expiration settings. Only the sub-object matching `type` is present; the others are omitted. properties: type: type: string enum: - NO_EXPIRATION - SLIDING_EXPIRATION - FIXED_DURATION - CALENDAR_EXPIRATION description: Expiration model for tier membership. fixed_duration: $ref: '#/components/schemas/TierStructureExpirationFixedDuration' description: >- Fixed duration settings. Present only when `type` is `FIXED_DURATION`. calendar_expiration: $ref: '#/components/schemas/TierStructureExpirationCalendarExpiration' description: >- Calendar expiration settings. Present only when `type` is `CALENDAR_EXPIRATION`. sliding_expiration: $ref: '#/components/schemas/TierStructureExpirationSlidingExpiration' description: >- Sliding expiration settings. Present only when `type` is `SLIDING_EXPIRATION`. TierStructureDowngrade: type: object description: Downgrade settings. properties: type: type: string enum: - MULTI_LEVEL - SINGLE_LEVEL - NO_DOWNGRADE description: Downgrade model. grace_period: $ref: '#/components/schemas/TierStructureDowngradeGracePeriod' description: >- Grace period before the downgrade takes effect. Omitted when not configured. TierStructurePointEarnedPeriod: type: object description: Points earned tracking period. properties: value: type: integer description: Length of the tracking period, expressed in `unit` units. unit: type: string enum: - DAY - WEEK - MONTH - YEAR description: Unit of the tracking period. TierStructureExpirationFixedDuration: type: object description: Fixed duration expiration settings. properties: period: $ref: '#/components/schemas/TierStructureExpirationPeriod' description: Duration after which the tier membership expires. TierStructureExpirationCalendarExpiration: type: object description: Calendar expiration settings. properties: calendar_dates: type: array description: Calendar dates on which tier membership expires. items: $ref: '#/components/schemas/TierStructureExpirationCalendarDate' TierStructureExpirationSlidingExpiration: type: object description: Sliding expiration settings. properties: earning_activity: type: boolean description: Whether point earning activity extends the tier membership. spending_activity: type: boolean description: Whether point spending activity extends the tier membership. custom_activity: type: boolean description: Whether custom activities extend the tier membership. custom_activity_types: type: array description: Custom activity type names that extend the tier membership. items: type: string description: Custom activity type name. period: $ref: '#/components/schemas/TierStructureExpirationPeriod' description: Sliding period after the last qualifying activity. TierStructureDowngradeGracePeriod: type: object description: Downgrade grace period. properties: value: type: integer description: Length of the grace period, expressed in `unit` units. unit: type: string enum: - DAY - MONTH - YEAR description: Unit of the grace period. round_up: type: boolean description: Whether the grace period end is rounded up to the end of the unit. TierStructureExpirationPeriod: type: object description: | Expiration period. The same shape is used for fixed duration and sliding expiration periods. properties: value: type: integer description: Length of the period, expressed in `unit` units. unit: type: string enum: - DAY - MONTH - YEAR description: Unit of the period. TierStructureExpirationCalendarDate: type: object description: A recurring calendar date. properties: day: type: integer minimum: 1 maximum: 31 description: Day of the month (1-31). month: type: integer minimum: 1 maximum: 12 description: Month of the year (1-12). 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 ````