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

# List tier structure activities

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

## Request

- Base URL: `https://api.voucherify.io`
- URL: `https://api.voucherify.io/v2/loyalties/tier-structures/{tierStructureId}/activities`
- 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 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`.

## Query parameters

- `limit` union
  - number
  - string
- `order` union
  - 'created_at' | '-created_at'
  - string[]
- `cursor` string, nullable
- `filters` LoyaltiesTierStructuresActivitiesListRequestQuery: Request query schema for **GET** `/v2/loyalties/tier-structures/{tierStructureId}/activities`.
  - `junction` 'AND' | 'OR', nullable: Joins the field filters. Allowed values are `AND` and `OR`. Defaults to `AND`.
  - `id` LoyaltiesTierStructuresActivitiesListRequestQueryId: 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]+$`.
    - `conditions` object, required: Condition operators applied to the field.
      - `$is` union: Matches one value. A string or a one-element array. Format `lats_[a-f0-9]+`.
        - string
        - string[]
      - `$is_not` union: Excludes one value. A string or a one-element array. Format `lats_[a-f0-9]+`.
        - string
        - string[]
      - `$in` union: Matches any of the values. A string or an array of 1 to 100 values. Format `lats_[a-f0-9]+`.
        - string
        - string[]
      - `$not_in` union: Excludes any of the values. A string or an array of 1 to 100 values. Format `lats_[a-f0-9]+`.
        - string
        - string[]
  - `type` LoyaltiesTierStructuresActivitiesListRequestQueryType: Enum field filter for activity `type`. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed values are the tier structure activity types.
    - `conditions` object, required: Condition operators applied to the field.
      - `$is` union: Matches one value. A string or a one-element array.
        - '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'
        - string[]
      - `$is_not` union: Excludes one value. A string or a one-element array.
        - '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'
        - string[]
      - `$in` union: Matches any of the values. A string or an array of 1 to 10 values.
        - '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'
        - string[]
      - `$not_in` union: Excludes any of the values. A string or an array of 1 to 10 values.
        - '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'
        - string[]
  - `created_at` TierStructureFilterDateField: 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.
    - `conditions` object, required: Condition operators applied to the field.
      - `$before` union: Matches dates before the given value. An ISO 8601 date-time, as a string or a one-element array.
        - string
        - string[]
      - `$after` union: Matches dates after the given value. An ISO 8601 date-time, as a string or a one-element array.
        - string
        - string[]
      - `$is` union: Matches a date exactly the given number of days ago. A non-negative integer, as a string or a one-element array.
        - string
        - string[]
      - `$more_than` union: Matches dates more than the given number of days ago. A non-negative integer, as a string or a one-element array.
        - string
        - string[]
      - `$less_than` union: Matches dates less than the given number of days ago. A non-negative integer, as a string or a one-element array.
        - string
        - string[]
      - `$has_value` string, nullable: Matches when the field is set. The condition value is ignored.
      - `$is_unknown` string, nullable: Matches when the field is not set. The condition value is ignored.

## Response `200`

Paginated list of tier structure activities.

- V2LoyaltiesTierStructuresActivitiesListResponseBody: Cursor-paginated list of tier structure activities.
  - `data` TierStructureActivity[], required: Activities on the current page.
    - `id` string, required: Unique activity identifier.
    - `type` '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', required: Activity type.
    - `data` TierStructureActivityData, required: 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.
      - `tier_structure` TierStructure, required: Tier structure resource.
        - `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 structure identifier.
        - `name` string, required: Display name of the tier structure.
        - `type` 'POINT_BALANCE' | 'POINT_EARNED', required: Tier qualification tracking model.
        - `point_balance` LoyaltyV2ActivityTierStructurePointBalance: Point balance tracking settings.
          - `card_definition_id` string: Unique identifier of the card definition whose point balance is tracked.
        - `point_earned` TierStructurePointEarned: Points earned tracking settings.
          - `card_definition_id` string: Unique identifier of the card definition whose earned points are tracked.
          - `period` LoyaltyV2ActivityTierStructurePointEarnedPeriod: Points earned tracking period.
            - `value` integer: Length of the tracking period, expressed in `unit` units.
            - `unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR': Unit of the tracking period.
          - `type` 'IMMEDIATELY' | 'NEXT_TRACKING_PERIOD': When a tier change resulting from earned points takes effect.
        - `expiration` TierStructureExpiration, required: Tier membership expiration settings. Only the sub-object matching `type` is present; the others are omitted.
          - `type` 'NO_RETENTION' | 'SLIDING_EXPIRATION' | 'FIXED_DURATION' | 'CALENDAR_EXPIRATION': Expiration model for tier membership.
          - `fixed_duration` TierStructureExpirationFixedDuration: Fixed duration expiration settings.
            - `period` LoyaltyV2ActivityTierStructureExpirationPeriod: Expiration period. The same shape is used for fixed duration and sliding expiration periods.
              - …
          - `calendar_expiration` TierStructureExpirationCalendarExpiration: Calendar expiration settings.
            - `calendar_dates` LoyaltyV2ActivityTierStructureExpirationCalendarDate[]: Calendar dates on which tier membership expires.
              - …
          - `sliding_expiration` TierStructureExpirationSlidingExpiration: Sliding expiration settings.
            - `earning_activity` boolean: Whether point earning activity extends the tier membership.
            - `spending_activity` boolean: Whether point spending activity extends the tier membership.
            - `custom_activity` boolean: Whether custom activities extend the tier membership.
            - `custom_activity_types` string[]: Custom activity type names that extend the tier membership.
            - `period` LoyaltyV2ActivityTierStructureExpirationPeriod: Expiration period. The same shape is used for fixed duration and sliding expiration periods.
              - …
        - `downgrade` TierStructureDowngrade, required: Downgrade settings.
          - `type` 'MULTI_LEVEL' | 'SINGLE_LEVEL' | 'NO_DOWNGRADE': Downgrade model.
          - `grace_period` LoyaltyV2ActivityTierStructureDowngradeGracePeriod: Downgrade grace period.
            - `value` integer: Length of the grace period, expressed in `unit` units.
            - `unit` 'DAY' | 'MONTH' | 'YEAR': Unit of the grace period.
            - `round_up` boolean: Whether the grace period end is rounded up to the end of the unit.
        - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'DELETED', required: Current lifecycle status of the tier structure.
        - `object` 'tier_structure', required: Object type discriminator. Always `tier_structure`.
      - `tier` Tier: Tier resource.
        - `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`.
      - `program` object: 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` object: 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.
    - `created_at` string, date-time, required: Timestamp of when the activity occurred (ISO 8601).
    - `group_id` string: Unique identifier grouping related activities that were produced by the same operation. Omitted when not set.
    - `source` TierStructureActivitySource: Origin of an activity.
      - `channel` 'USER_PORTAL' | 'API' | 'CLIENT_API' | 'INTERNAL': Channel through which the activity was triggered.
      - `user` object: User who triggered the activity. Omitted when not applicable.
        - `id` string: Unique identifier of the user.
      - `api_key` object: API key used to trigger the activity. Omitted when not applicable.
        - `name` string: Name of the API key.
        - `app_id` string: Application id of the API key.
        - `client_app_id` string: Client application id of the API key.
    - `tier_structure_id` string, required: Unique identifier of the tier structure the activity relates to.
  - `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`: 20 breaking, 3 warning, 2 info
  - the `allOf[#/components/schemas/TierStructureActivityListResponse]/data/items/data/tier` response's property type changed from `object` to no type for status `200`
  - the `allOf[#/components/schemas/TierStructureActivityListResponse]/data/items/data/tier_structure` response's property type changed from `object` to no type for status `200`
  - removed the required property `allOf[#/components/schemas/TierStructureActivityListResponse]/data/items/data/tier/created_at` from the response with the `200` status
  - removed the required property `allOf[#/components/schemas/TierStructureActivityListResponse]/data/items/data/tier/downgrade` from the response with the `200` status
  - …21 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/tier-structures/:tierStructureId/activities/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)