> ## 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 structure activities > ⚠️ **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 activities recorded for the tier structure (creation, updates, state transitions, assignments, and nested tier changes). 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}/activities 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}/activities: get: tags: - Tier Structures summary: List tier structure activities 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 activities recorded for the tier structure (creation, updates, state transitions, assignments, and nested tier changes). The same field cannot be requested in both ascending and descending order at once. Default order is `-created_at`. operationId: listTierStructureActivities 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' - type: array items: type: string enum: - created_at - '-created_at' - name: cursor in: query required: false description: > Pagination cursor returned in the `cursor.next` field of a previous response. Must match the tier structure activities cursor id format. schema: type: string pattern: ^lcrsats_[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[type][conditions][$is]=vl.tier_structure.created`). schema: $ref: '#/components/schemas/TierStructureActivityListFilters' responses: '200': description: Paginated list of tier structure activities. content: application/json: schema: $ref: '#/components/schemas/TierStructureActivityListResponse' '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: TierStructureActivityListFilters: type: object description: > Filters for the tier structure activities 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 activity id (ID field conditions, pattern `^lats_[a-f0-9]+$`). oneOf: - $ref: '#/components/schemas/TierStructureActivityFilterIdField' - type: 'null' type: description: Filter by activity type (enum field conditions). oneOf: - $ref: '#/components/schemas/TierStructureActivityFilterTypeField' - type: 'null' created_at: description: Filter by activity creation date (date field conditions). oneOf: - $ref: '#/components/schemas/TierStructureFilterDateField' - type: 'null' additionalProperties: false TierStructureActivityListResponse: type: object description: Cursor-paginated list of tier structure activities. properties: data: type: array description: Activities on the current page. items: $ref: '#/components/schemas/TierStructureActivity' 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: ^lcrsats_[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. TierStructureActivityFilterIdField: type: object description: > ID field filter for tier structure activity ids. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Each condition accepts a single string or an array of strings matching `^lats_[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: ^lats_[a-f0-9]+$ - type: array minItems: 1 maxItems: 1 items: type: string pattern: ^lats_[a-f0-9]+$ - type: 'null' $is_not: description: Matches when the field does not equal the given id. oneOf: - type: string pattern: ^lats_[a-f0-9]+$ - type: array minItems: 1 maxItems: 1 items: type: string pattern: ^lats_[a-f0-9]+$ - type: 'null' $in: description: Matches when the field equals any of the given ids (up to 100). oneOf: - type: string pattern: ^lats_[a-f0-9]+$ - type: array minItems: 1 maxItems: 100 items: type: string pattern: ^lats_[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: ^lats_[a-f0-9]+$ - type: array minItems: 1 maxItems: 100 items: type: string pattern: ^lats_[a-f0-9]+$ - type: 'null' required: - conditions additionalProperties: false TierStructureActivityFilterTypeField: type: object description: > Enum field filter for activity `type`. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed values are the tier structure activity types. 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: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: array minItems: 1 maxItems: 1 items: type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: 'null' $is_not: description: Matches when the field does not equal the given value. oneOf: - type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: array minItems: 1 maxItems: 1 items: type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: 'null' $in: description: >- Matches when the field equals any of the given values (up to 10). oneOf: - type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: array minItems: 1 maxItems: 10 items: type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: 'null' $not_in: description: >- Matches when the field equals none of the given values (up to 10). oneOf: - type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted - type: array minItems: 1 maxItems: 10 items: type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.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 TierStructureActivity: type: object description: | A tier structure activity record. properties: id: type: string pattern: ^lats_[a-f0-9]+$ description: Unique activity identifier. type: type: string enum: - vl.tier_structure.created - vl.tier_structure.updated - vl.tier_structure.deleted - vl.tier_structure.activated - vl.tier_structure.deactivated - vl.tier_structure.drafted - vl.tier_structure.assigned - vl.tier_structure.unassigned - vl.tier_structure.tier.created - vl.tier_structure.tier.updated - vl.tier_structure.tier.deleted description: Activity type. data: $ref: '#/components/schemas/TierStructureActivityData' description: Activity payload snapshot. created_at: type: string format: date-time description: Timestamp of when the activity occurred (ISO 8601). group_id: type: string description: > Identifier grouping related activities that were produced by the same operation. Omitted when not set. source: $ref: '#/components/schemas/TierStructureActivitySource' description: >- Origin of the activity (channel, user, API key). Omitted when not set. tier_structure_id: type: string pattern: ^lts_[a-f0-9]+$ description: Identifier of the tier structure the activity relates to. required: - id - type - data - created_at - tier_structure_id TierStructureActivityData: type: object description: > Activity payload. Always contains a `tier_structure` snapshot. For `vl.tier_structure.tier.*` activities it additionally contains a `tier` snapshot; for `vl.tier_structure.assigned`/`vl.tier_structure.unassigned` activities it additionally contains `program` and `program_tier_structure` snapshots. properties: tier_structure: $ref: '#/components/schemas/TierStructure' description: Snapshot of the tier structure at the time of the activity. tier: $ref: '#/components/schemas/Tier' description: > Snapshot of the tier. Present only for `vl.tier_structure.tier.created`, `vl.tier_structure.tier.updated` and `vl.tier_structure.tier.deleted` activities. program: type: object description: | Snapshot of the loyalty program (documented in the Programs domain). Present only for `vl.tier_structure.assigned` and `vl.tier_structure.unassigned` activities. program_tier_structure: type: object description: > Snapshot of the program-to-tier-structure assignment (documented in the Programs domain). Present only for `vl.tier_structure.assigned` and `vl.tier_structure.unassigned` activities. required: - tier_structure TierStructureActivitySource: type: object description: Origin of an activity. properties: channel: type: string enum: - USER_PORTAL - API - CLIENT_API - INTERNAL description: Channel through which the activity was triggered. user: type: object description: User who triggered the activity. Omitted when not applicable. properties: id: type: string description: Identifier of the user. api_key: type: object description: API key used to trigger the activity. Omitted when not applicable. properties: name: type: string description: Name of the API key. app_id: type: string description: Application id of the API key. client_app_id: type: string description: Client application id of the API key. 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 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 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. 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. 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. 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. 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 ````