--- 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` Documentation in progress 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. 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`. ## Path parameters - `id` string, required ## Query parameters - `limit` integer - `order` union - 'created_at' | '-created_at' - string[] - `cursor` string - `filters` TierStructureActivityListFilters — Filters for the tier structure activities list. Each field accepts a `conditions` object; each filter field may also be null. - `junction` 'AND' | 'OR', nullable — Logical junction combining the field filters. Defaults to AND semantics. - `id` TierStructureActivityFilterIdField — 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 when the field equals the given id. - string - string[] - `$is_not` union — Matches when the field does not equal the given id. - string - string[] - `$in` union — Matches when the field equals any of the given ids (up to 100). - string - string[] - `$not_in` union — Matches when the field equals none of the given ids (up to 100). - string - string[] - `type` TierStructureActivityFilterTypeField — 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 when the field equals the given value. - '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 — Matches when the field does not equal the given value. - '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 when the field equals any of the given values (up to 10). - '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 — Matches when the field equals none of the given values (up to 10). - '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 when the field is before the given date. Value must be a valid date string. - string - string[] - `$after` union — Matches when the field is after the given date. Value must be a valid date string. - string - string[] - `$is` union — Matches by relative value. A non-negative integer. - string - string[] - `$more_than` union — Matches by relative value (greater than). A non-negative integer. - string - string[] - `$less_than` union — Matches by relative value (less than). A non-negative integer. - string - string[] - `$has_value` string, nullable — Matches when the field has any value. The value of this condition is ignored. - `$is_unknown` string, nullable — Matches when the field has no value. The value of this condition is ignored. ## Response `200` Paginated list of tier structure activities. - TierStructureActivityListResponse — 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. - `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` TierStructurePointBalance — 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` TierStructurePointEarnedPeriod — 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` TierStructureExpirationPeriod — Expiration period. The same shape is used for fixed duration and sliding expiration periods. - … - `calendar_expiration` TierStructureExpirationCalendarExpiration — Calendar expiration settings. - `calendar_dates` TierStructureExpirationCalendarDate[] — 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` TierStructureExpirationPeriod — 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` TierStructureDowngradeGracePeriod — 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. - `metadata` object, required — Free-form key/value object holding custom attributes. Defaults to `{}`. - `status` 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'DELETED', required — Current lifecycle status of the tier structure. - `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. - `object` 'tier_structure', required — Object type discriminator. Always `tier_structure`. - `tier` Tier — Tier resource. - `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` TierQualificationRulesPoints — 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` TierQualificationRulesSegment — Customer segment reference. - `id` string — Unique identifier of the customer segment. - `downgrade` TierDowngrade, required — Tier-level downgrade behavior. - `type` 'INHERIT' | 'NO_DOWNGRADE' — Downgrade model. Omitted when the tier has no downgrade configured. - `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. - `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. - `409` — Conflict - e.g. duplicate resource or invalid state transition. - `500` — Internal server error. --- [API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/versions/69be73b5cff0/schema)