--- title: "Update tier structure" method: PUT path: "/v2/loyalties/tier-structures/{tierStructureId}" tags: ["Tier Structures"] --- # Update tier structure `PUT /v2/loyalties/tier-structures/{tierStructureId}` 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. 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 — Unique 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 — Unique 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_RETENTION' | '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 — 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`. ## 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)