> ## 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 paginated, cursor-based list of tier structures with optional filtering and ordering. ## 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 API documentation for Voucherify Loyalty v2 system. Requires LOYALTY_V2 feature flag. servers: - url: https://api.voucherify.io description: Production security: - bearerAuth: [] X-App-Id: [] X-App-Token: [] tags: - 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: 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: 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: Incentives description: >- Manage incentive 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: Examines the earning of loyalty points for a loyalty program member. 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 paginated, cursor-based list of tier structures with optional filtering and ordering. operationId: listTierStructures parameters: - name: filters[junction] in: query required: false schema: type: string enum: - AND - OR description: Logical junction for combining filter conditions. - name: filters[id][conditions][$is] in: query required: false schema: type: string description: Filter by exact tier structure ID. - name: filters[id][conditions][$is_not] in: query required: false schema: type: string description: Exclude tier structures with this ID. - name: filters[id][conditions][$in] in: query required: false schema: type: array items: type: string maxItems: 100 description: Filter by multiple tier structure IDs. - name: filters[id][conditions][$not_in] in: query required: false schema: type: array items: type: string maxItems: 100 description: Exclude tier structures with these IDs. - name: filters[name][conditions][$is] in: query required: false schema: type: string description: Filter by exact name. - name: filters[name][conditions][$is_not] in: query required: false schema: type: string description: Exclude by exact name. - name: filters[name][conditions][$contains] in: query required: false schema: type: string description: Filter by name containing substring. - name: filters[name][conditions][$not_contain] in: query required: false schema: type: string description: Filter by name not containing substring. - name: filters[name][conditions][$starts_with] in: query required: false schema: type: string description: Filter by name starting with. - name: filters[name][conditions][$ends_with] in: query required: false schema: type: string description: Filter by name ending with. - name: filters[name][conditions][$in] in: query required: false schema: type: array items: type: string maxItems: 10 description: Filter by multiple names. - name: filters[name][conditions][$not_in] in: query required: false schema: type: array items: type: string maxItems: 10 description: Exclude tier structures with these names. - name: filters[name][conditions][$has_value] in: query required: false schema: type: string description: Filter for records where name has a value. - name: filters[name][conditions][$is_unknown] in: query required: false schema: type: string description: Filter for records where name is unknown. - name: filters[type][conditions][$is] in: query required: false schema: type: string enum: - POINT_BALANCE - POINT_EARNED description: Filter by exact tier structure type. - name: filters[type][conditions][$is_not] in: query required: false schema: type: string enum: - POINT_BALANCE - POINT_EARNED description: Exclude by tier structure type. - name: filters[type][conditions][$in] in: query required: false schema: type: array items: type: string enum: - POINT_BALANCE - POINT_EARNED maxItems: 10 description: Filter by multiple tier structure types. - name: filters[type][conditions][$not_in] in: query required: false schema: type: array items: type: string enum: - POINT_BALANCE - POINT_EARNED maxItems: 10 description: Exclude by multiple tier structure types. - name: filters[status][conditions][$is] in: query required: false schema: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED description: Filter by exact status. - name: filters[status][conditions][$is_not] in: query required: false schema: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED description: Exclude by status. - name: filters[status][conditions][$in] in: query required: false schema: type: array items: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED maxItems: 10 description: Filter by multiple statuses. - name: filters[status][conditions][$not_in] in: query required: false schema: type: array items: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED maxItems: 10 description: Exclude by multiple statuses. - name: filters[created_at][conditions][$before] in: query required: false schema: type: string format: date-time description: Filter for records created before this date. - name: filters[created_at][conditions][$after] in: query required: false schema: type: string format: date-time description: Filter for records created after this date. - name: filters[created_at][conditions][$is] in: query required: false schema: type: integer minimum: 0 description: Filter for records created exactly N days ago. - name: filters[created_at][conditions][$more_than] in: query required: false schema: type: integer minimum: 0 description: Filter for records created more than N days ago. - name: filters[created_at][conditions][$less_than] in: query required: false schema: type: integer minimum: 0 description: Filter for records created less than N days ago. - name: filters[created_at][conditions][$has_value] in: query required: false schema: type: string description: Filter for records where created_at has a value. - name: filters[created_at][conditions][$is_unknown] in: query required: false schema: type: string description: Filter for records where created_at is unknown. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 10 description: Maximum number of results to return (1-100). - name: order in: query required: false schema: type: array items: type: string enum: - '-created_at' - created_at - name - '-name' - type - '-type' - status - '-status' description: 'Sort order. Prefix with `-` for descending. Default: `-created_at`.' - name: cursor in: query required: false schema: type: string description: Cursor for pagination. Obtained from a previous list response. responses: '200': description: List of tier structures content: application/json: schema: $ref: '#/components/schemas/TierStructureListResponse' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/InternalServerError' components: schemas: TierStructureListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/TierStructure' cursor: oneOf: - $ref: '#/components/schemas/PaginationCursor' - type: 'null' object: type: string enum: - list required: - data - object TierStructure: type: object description: A tier structure resource as returned by the API. properties: id: type: string description: Unique tier structure identifier. name: type: string maxLength: 200 description: Display name. type: type: string enum: - POINT_BALANCE - POINT_EARNED description: Tiering model type. card_definition_id: type: string description: ID of the linked card definition. point_earned: oneOf: - $ref: '#/components/schemas/TierStructurePointEarned' - type: 'null' description: >- Point-earned tracking configuration. Present when `type` is `POINT_EARNED`. expiration: oneOf: - $ref: '#/components/schemas/TierStructureExpiration' - type: 'null' description: Tier qualification expiration settings. downgrade: oneOf: - $ref: '#/components/schemas/TierStructureDowngrade' - type: 'null' description: Downgrade behaviour settings. metadata: type: object description: Custom key-value metadata. additionalProperties: true status: type: string enum: - DRAFT - ACTIVE - INACTIVE - DELETED description: Current lifecycle status. created_at: type: string format: date-time description: ISO 8601 creation timestamp. updated_at: oneOf: - type: string format: date-time - type: 'null' description: ISO 8601 last-update timestamp. object: type: string enum: - tier_structure description: Object type discriminator. required: - id - name - type - card_definition_id - metadata - status - created_at - object PaginationCursor: type: object description: Cursor for fetching the next page of results. properties: next: type: string description: >- Cursor token to pass as the `cursor` query parameter for the next page. expires_at: type: string format: date-time description: ISO 8601 timestamp when this cursor expires. required: - next - expires_at ErrorResponse: type: object description: Standard error response. properties: code: type: integer description: HTTP status code. key: type: string description: Machine-readable error key. message: type: string description: Human-readable error message. details: type: string description: Additional error details. request_id: type: - string - 'null' description: Request identifier for tracing. resource_id: type: string description: Related resource identifier (when applicable). resource_type: type: string description: Related resource type (when applicable). required: - code - key - message TierStructurePointEarned: type: object properties: period: $ref: '#/components/schemas/TierStructurePointEarnedPeriod' type: type: string enum: - IMMEDIATELY - NEXT_TRACKING_PERIOD description: When the earned points are applied to tier qualification. required: - period - type TierStructureExpiration: type: object description: > Expiration configuration. The sub-object that is present depends on `type`: - `NO_EXPIRATION`: no sub-objects - `ROLLING_EXPIRATION`: `rolling_expiration` required - `CALENDAR_EXPIRATION`: `calendar_expiration` required - `SLIDING_EXPIRATION`: `sliding_expiration` required properties: type: type: string enum: - NO_EXPIRATION - SLIDING_EXPIRATION - ROLLING_EXPIRATION - CALENDAR_EXPIRATION rolling_expiration: oneOf: - $ref: '#/components/schemas/TierStructureRollingExpiration' - type: 'null' calendar_expiration: oneOf: - $ref: '#/components/schemas/TierStructureCalendarExpiration' - type: 'null' sliding_expiration: oneOf: - $ref: '#/components/schemas/TierStructureSlidingExpiration' - type: 'null' required: - type TierStructureDowngrade: type: object properties: type: type: string enum: - MULTI_LEVEL - SINGLE_LEVEL - NO_DOWNGRADE description: Downgrade strategy. grace_period: oneOf: - $ref: '#/components/schemas/TierStructureDowngradeGracePeriod' - type: 'null' description: Optional grace period before downgrade takes effect. TierStructurePointEarnedPeriod: type: object properties: value: type: integer minimum: 1 description: Duration value. unit: type: string enum: - HOUR - DAY - WEEK - MONTH - YEAR description: Duration unit. required: - value - unit TierStructureRollingExpiration: type: object properties: period: $ref: '#/components/schemas/TierStructureRollingExpirationPeriod' required: - period TierStructureCalendarExpiration: type: object properties: calendar_dates: type: array items: $ref: '#/components/schemas/TierStructureCalendarDate' minItems: 1 maxItems: 20 description: List of calendar dates when tier qualification expires. required: - calendar_dates TierStructureSlidingExpiration: type: object description: Sliding window expiration that resets on qualifying activity. properties: earning_activity: type: boolean description: Whether earning activity resets the expiration window. spending_activity: type: boolean description: Whether spending activity resets the expiration window. custom_activity: type: boolean description: Whether custom activity resets the expiration window. custom_activity_types: type: array items: type: string maxItems: 10 description: >- Custom event schema IDs that reset the window. Required when `custom_activity` is true. period: $ref: '#/components/schemas/TierStructureSlidingExpirationPeriod' required: - earning_activity - spending_activity - custom_activity - period TierStructureDowngradeGracePeriod: type: object properties: value: type: integer minimum: 1 description: 'Duration value. Max depends on unit: DAY=90, MONTH=12, YEAR=5.' unit: type: string enum: - DAY - MONTH - YEAR round_up: type: boolean description: Whether to round up the grace period to the next full unit. required: - value - unit TierStructureRollingExpirationPeriod: type: object properties: value: type: integer minimum: 1 description: 'Duration value. Max depends on unit: DAY=90, MONTH=12, YEAR=5.' unit: type: string enum: - DAY - MONTH - YEAR required: - value - unit TierStructureCalendarDate: type: object description: >- Day/month pair. Day range depends on month (Feb max 29, Apr/Jun/Sep/Nov max 30, others max 31). properties: day: type: integer minimum: 1 maximum: 31 month: type: integer minimum: 1 maximum: 12 required: - day - month TierStructureSlidingExpirationPeriod: type: object properties: value: type: integer minimum: 1 description: 'Duration value. Max depends on unit: DAY=90, MONTH=12, YEAR=5.' unit: type: string enum: - DAY - MONTH - YEAR required: - value - unit responses: BadRequest: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 ````