--- title: "List tier structures" method: GET path: "/v2/loyalties/tier-structures" tags: ["Tier Structures"] --- # List tier structures `GET /v2/loyalties/tier-structures` 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 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 — 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. - `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/69be73b5cff0/schema)