--- title: "List tier structures" method: GET path: "/v2/loyalties/tier-structures" tags: ["Tier Structures"] --- # List tier structures `GET /v2/loyalties/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](https://www.voucherify.io/contact-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`. ## Query parameters - `limit` integer - `order` union - '-created_at' | 'created_at' | 'name' | '-name' | 'type' | '-type' | 'status' | '-status' - string[] - `cursor` string - `filters` TierStructureListFilters — Filters for the tier structures 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` TierStructureFilterIdField — 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]+$`. - `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[] - `name` TierStructureFilterStringField — 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. - `conditions` object, required — Condition operators applied to the field. - `$is` union — Matches when the field equals the given value. - string - string[] - `$is_not` union — Matches when the field does not equal the given value. - string - string[] - `$contains` union — Matches when the field contains the given substring. - string - string[] - `$not_contain` union — Matches when the field does not contain the given substring. - string - string[] - `$starts_with` union — Matches when the field starts with the given prefix. - string - string[] - `$ends_with` union — Matches when the field ends with the given suffix. - string - string[] - `$in` union — Matches when the field equals any of the given values (up to 10). - string - string[] - `$not_in` union — Matches when the field equals none of the given values (up to 10). - 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. - `type` TierStructureFilterTypeField — Enum field filter for tier structure `type`. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed values: `POINT_BALANCE`, `POINT_EARNED`. - `conditions` object, required — Condition operators applied to the field. - `$is` union — Matches when the field equals the given value. - 'POINT_BALANCE' | 'POINT_EARNED' - string[] - `$is_not` union — Matches when the field does not equal the given value. - 'POINT_BALANCE' | 'POINT_EARNED' - string[] - `$in` union — Matches when the field equals any of the given values (up to 10). - 'POINT_BALANCE' | 'POINT_EARNED' - string[] - `$not_in` union — Matches when the field equals none of the given values (up to 10). - 'POINT_BALANCE' | 'POINT_EARNED' - string[] - `status` TierStructureFilterStatusField — Enum field filter for tier structure `status`. Allowed conditions: `$is`, `$is_not`, `$in`, `$not_in`. Allowed values: `DRAFT`, `ACTIVE`, `INACTIVE`, `DELETED`. - `conditions` object, required — Condition operators applied to the field. - `$is` union — Matches when the field equals the given value. - 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'DELETED' - string[] - `$is_not` union — Matches when the field does not equal the given value. - 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'DELETED' - string[] - `$in` union — Matches when the field equals any of the given values (up to 10). - 'DRAFT' | 'ACTIVE' | 'INACTIVE' | 'DELETED' - string[] - `$not_in` union — Matches when the field equals none of the given values (up to 10). - 'DRAFT' | 'ACTIVE' | 'INACTIVE' | '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 structures. - TierStructureListResponse — Cursor-paginated list of tier structures. - `data` TierStructure[], required — Tier structures on the current page. - `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 — Identifier of the card definition whose point balance is tracked. - `point_earned` TierStructurePointEarned — Points earned tracking settings. - `card_definition_id` string — 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_EXPIRATION' | '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. - `value` integer — Length of the period, expressed in `unit` units. - `unit` 'DAY' | 'MONTH' | 'YEAR' — Unit of the period. - `calendar_expiration` TierStructureExpirationCalendarExpiration — Calendar expiration settings. - `calendar_dates` TierStructureExpirationCalendarDate[] — Calendar dates on which tier membership expires. - `day` integer — Day of the month (1-31). - `month` integer — Month of the year (1-12). - `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. - `value` integer — Length of the period, expressed in `unit` units. - `unit` 'DAY' | 'MONTH' | 'YEAR' — Unit of the period. - `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`. - `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/revisions/f6f2f3388362/schema)