--- title: "Update tier structure" method: PUT path: "/v2/loyalties/tier-structures/{tierStructureId}" tags: ["Tier Structures"] --- # Update tier structure `PUT /v2/loyalties/tier-structures/{tierStructureId}` 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. Updates a tier structure. All properties are optional; provided values are merged with the existing tier structure. When `type` is provided as `POINT_EARNED`, `point_earned` is required and `point_balance` must be null; when `type` is `POINT_BALANCE`, `point_balance` is required and `point_earned` must be null. When the tier structure is not in `DRAFT` status, only `name` and `metadata` may be updated; attempting to update other properties results in a validation error. ## Path parameters - `id` string, required ## Request body - TierStructureUpdateRequest — Request body for updating a tier structure. All properties are optional; no additional properties are allowed. When the tier structure is not in `DRAFT` status, only `name` and `metadata` may be updated. - `name` string — Display name of the tier structure. - `type` 'POINT_BALANCE' | 'POINT_EARNED' — Tier qualification tracking model. If provided, the matching tracking settings object (`point_balance` or `point_earned`) becomes required. - `point_balance` TierStructurePointBalanceUpsert — Point balance tracking settings. Members qualify for tiers based on the current balance of the referenced card definition. - `card_definition_id` string, required — Identifier of the card definition whose point balance is tracked. - `point_earned` TierStructurePointEarnedUpsert — Points earned tracking settings. Members qualify for tiers based on points earned on the referenced card definition within a tracking period. - `card_definition_id` string, required — Identifier of the card definition whose earned points are tracked. - `period` TierStructurePointEarnedPeriodUpsert, required — Points earned tracking period. The maximum `value` depends on `unit`: 90 for `DAY`, 52 for `WEEK`, 12 for `MONTH`, 5 for `YEAR`. - `value` integer, required — Length of the tracking period, expressed in `unit` units. Minimum 1. Maximum depends on `unit` (DAY: 90, WEEK: 52, MONTH: 12, YEAR: 5). - `unit` 'DAY' | 'WEEK' | 'MONTH' | 'YEAR', required — Unit of the tracking period. - `type` 'IMMEDIATELY' | 'NEXT_TRACKING_PERIOD', required — When a tier change resulting from earned points takes effect: `IMMEDIATELY` or at the start of the `NEXT_TRACKING_PERIOD`. - `expiration` TierStructureExpirationUpsert — Tier membership expiration settings. Exactly the sub-object matching `type` is required; the remaining sub-objects must be null/omitted. - `type` 'NO_EXPIRATION' | 'SLIDING_EXPIRATION' | 'FIXED_DURATION' | 'CALENDAR_EXPIRATION', required — Expiration model for tier membership. Required. - `fixed_duration` TierStructureExpirationFixedDurationUpsert — Fixed duration expiration settings. Tier membership expires after a fixed period. - `period` TierStructureExpirationFixedDurationPeriodUpsert, required — Fixed duration expiration period. - `value` integer, required — Length of the expiration period, expressed in `unit` units. Minimum 1. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Unit of the expiration period. - `calendar_expiration` TierStructureExpirationCalendarExpirationUpsert — Calendar expiration settings. Tier membership expires on fixed calendar dates. - `calendar_dates` TierStructureExpirationCalendarDateUpsert[], required — Calendar dates (day + month) on which tier membership expires. 1-20 items. - `day` integer, required — Day of the month (1-31). Maximum depends on `month`: February allows up to 29; April, June, September and November allow up to 30; other months allow up to 31. - `month` integer, required — Month of the year (1-12). - `sliding_expiration` TierStructureExpirationSlidingExpirationUpsert — Sliding expiration settings. Tier membership expiration slides forward on the configured member activities. - `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. Up to 10 unique items. Defaults to an empty array when omitted. - `period` TierStructureExpirationSlidingExpirationPeriodUpsert, required — Sliding expiration period. - `value` integer, required — Length of the sliding period, expressed in `unit` units. Minimum 1. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Unit of the sliding period. - `downgrade` TierStructureDowngradeUpsert — Downgrade settings. Controls how members are moved to lower tiers on expiration. When `type` is `NO_DOWNGRADE`, `grace_period` must be null/omitted. - `type` 'MULTI_LEVEL' | 'SINGLE_LEVEL' | 'NO_DOWNGRADE', required — Downgrade model. `MULTI_LEVEL` allows dropping multiple tiers at once, `SINGLE_LEVEL` drops one tier at a time, `NO_DOWNGRADE` disables downgrades. Required. - `grace_period` TierStructureDowngradeGracePeriodUpsert — Downgrade grace period. - `value` integer, required — Length of the grace period, expressed in `unit` units. Minimum 1. - `unit` 'DAY' | 'MONTH' | 'YEAR', required — Unit of the grace period. - `round_up` boolean — Whether the grace period end is rounded up to the end of the unit. - `metadata` object, nullable — Free-form key/value object holding custom attributes. ## Response `200` The updated tier structure. - TierStructure — 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 — 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`. ## 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/f6f2f3388362/schema)