> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Update tier structure
>
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may be 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.
## OpenAPI
````yaml /openapi/loyalties-v2.json put /v2/loyalties/tier-structures/{tierStructureId}
openapi: 3.1.0
info:
title: Voucherify Loyalty v2 API
version: 2.0.0
description: >-
Complete OpenAPI specification for the Voucherify Loyalty v2 API.
All endpoints require the LOYALTY_V2 feature flag.
Combined from per-domain specs: programs.yaml, members.yaml,
program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
- url: '{protocol}://{host}'
variables:
protocol:
default: https
enum:
- https
- http
host:
default: api.voucherify.io
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
tags:
- name: Programs
description: >-
Loyalty program CRUD, lifecycle management, program-scoped resource
assignments (card definitions, earning rules, rewards, tier structures),
member management (create, list, get, activate, deactivate, delete),
membership retrieval (member + program + cards with tier progress, by
customer ID, customer source ID, or member ID), card operations (points
adjustment, pending points, expiring points, transactions), reward
purchases, and activity history.
- name: Card Definitions
description: >-
CRUD operations, lifecycle management, and activity history for card
definitions. Card definitions describe the configuration for loyalty
cards, including code generation, points expiration, earning/spending
limits, pending points, refunds, and balance settings.
- name: Earning Rules
description: >-
Manage earning rules that define how customers earn points or receive
incentives based on triggers (events, segments, custom events). Includes
CRUD, lifecycle, and activity history.
- name: Tier Structures
description: >-
CRUD operations, lifecycle management, and activity history for tier
structures. Includes nested tier definitions (create, list, update,
delete) within tier structures. Tier structures define the tiering model
for loyalty programs — how members qualify for and move between tiers.
- name: Benefits
description: >-
Manage benefit definitions (fixed points, proportional points, material,
digital). Includes CRUD, lifecycle transitions, and activity history.
- name: Rewards
description: >-
CRUD, lifecycle operations, and activity history for reward definitions.
Rewards can be material (product/SKU) or digital (discount coupons, gift
vouchers).
- name: Examine
description: >-
Evaluation endpoints that estimate earning opportunities and reward
availability for a customer across their loyalty program memberships,
without side effects.
paths:
/v2/loyalties/tier-structures/{tierStructureId}:
put:
tags:
- Tier Structures
summary: Update tier structure
description: >-
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The
parameters, fields, request and response bodies, and other data may be
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.
operationId: updateTierStructure
parameters:
- name: id
in: path
required: true
description: Unique tier structure identifier.
schema:
type: string
pattern: ^lts_[a-f0-9]+$
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TierStructureUpdateRequest'
responses:
'200':
description: The updated tier structure.
content:
application/json:
schema:
$ref: '#/components/schemas/TierStructure'
'400':
description: >-
Validation error - request body or query parameters failed
validation, or the operation is not allowed in the current resource
state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - e.g. duplicate resource or invalid state transition.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
TierStructureUpdateRequest:
type: object
description: >-
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.
properties:
name:
type: string
minLength: 1
maxLength: 200
description: Display name of the tier structure.
type:
type: string
enum:
- POINT_BALANCE
- POINT_EARNED
description: >-
Tier qualification tracking model. If provided, the matching
tracking settings
object (`point_balance` or `point_earned`) becomes required.
point_balance:
description: >-
Point balance tracking settings. Required (non-null) when `type` is
provided as
`POINT_BALANCE`; must be null when `type` is provided as
`POINT_EARNED`.
oneOf:
- $ref: '#/components/schemas/TierStructurePointBalanceUpsert'
- type: 'null'
point_earned:
description: >-
Points earned tracking settings. Required (non-null) when `type` is
provided as
`POINT_EARNED`; must be null when `type` is provided as
`POINT_BALANCE`.
oneOf:
- $ref: '#/components/schemas/TierStructurePointEarnedUpsert'
- type: 'null'
expiration:
description: Tier membership expiration settings.
oneOf:
- $ref: '#/components/schemas/TierStructureExpirationUpsert'
- type: 'null'
downgrade:
description: Downgrade behavior applied when tier membership expires.
oneOf:
- $ref: '#/components/schemas/TierStructureDowngradeUpsert'
- type: 'null'
metadata:
description: Free-form key/value object holding custom attributes.
oneOf:
- type: object
- type: 'null'
additionalProperties: false
allOf:
- if:
properties:
type:
const: POINT_EARNED
required:
- type
then:
required:
- point_earned
properties:
point_earned:
$ref: '#/components/schemas/TierStructurePointEarnedUpsert'
point_balance:
type: 'null'
- if:
properties:
type:
const: POINT_BALANCE
required:
- type
then:
required:
- point_balance
properties:
point_balance:
$ref: '#/components/schemas/TierStructurePointBalanceUpsert'
point_earned:
type: 'null'
TierStructure:
type: object
description: Tier structure resource.
properties:
id:
type: string
description: Unique tier structure identifier.
pattern: ^lts_[a-f0-9]+$
name:
type: string
description: Display name of the tier structure.
type:
type: string
enum:
- POINT_BALANCE
- POINT_EARNED
description: Tier qualification tracking model.
point_balance:
$ref: '#/components/schemas/TierStructurePointBalance'
description: >-
Point balance tracking settings. Present only when `type` is
`POINT_BALANCE`;
omitted otherwise.
point_earned:
$ref: '#/components/schemas/TierStructurePointEarned'
description: >-
Points earned tracking settings. Present only when `type` is
`POINT_EARNED`;
omitted otherwise.
expiration:
$ref: '#/components/schemas/TierStructureExpiration'
description: Tier membership expiration settings.
downgrade:
$ref: '#/components/schemas/TierStructureDowngrade'
description: Downgrade behavior applied when tier membership expires.
metadata:
type: object
description: >-
Free-form key/value object holding custom attributes. Defaults to
`{}`.
status:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
description: Current lifecycle status of the tier structure.
created_at:
type: string
format: date-time
description: Creation timestamp (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: Last update timestamp (ISO 8601), or `null` if never updated.
object:
type: string
const: tier_structure
description: Object type discriminator. Always `tier_structure`.
required:
- id
- name
- type
- expiration
- downgrade
- metadata
- status
- created_at
- updated_at
- object
ErrorResponse:
type: object
description: Standard error response returned by all Loyalty v2 endpoints.
properties:
code:
type: integer
description: HTTP status code of the error.
key:
type: string
description: Machine-readable error key.
message:
type: string
description: Human-readable error message.
details:
type: string
description: Additional details about the error.
request_id:
type: string
description: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
TierStructurePointBalanceUpsert:
type: object
description: >-
Point balance tracking settings. Members qualify for tiers based on the
current
balance of the referenced card definition.
properties:
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition whose point balance is
tracked.
required:
- card_definition_id
additionalProperties: false
TierStructurePointEarnedUpsert:
type: object
description: >-
Points earned tracking settings. Members qualify for tiers based on
points earned
on the referenced card definition within a tracking period.
properties:
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition whose earned points are
tracked.
period:
$ref: '#/components/schemas/TierStructurePointEarnedPeriodUpsert'
description: Tracking period during which earned points are accumulated.
type:
type: string
enum:
- IMMEDIATELY
- NEXT_TRACKING_PERIOD
description: >-
When a tier change resulting from earned points takes effect:
`IMMEDIATELY`
or at the start of the `NEXT_TRACKING_PERIOD`.
required:
- card_definition_id
- period
- type
additionalProperties: false
TierStructureExpirationUpsert:
type: object
description: >-
Tier membership expiration settings. Exactly the sub-object matching
`type` is
required; the remaining sub-objects must be null/omitted.
properties:
type:
type: string
enum:
- NO_RETENTION
- SLIDING_EXPIRATION
- FIXED_DURATION
- CALENDAR_EXPIRATION
description: Expiration model for tier membership. Required.
fixed_duration:
description: >-
Fixed duration expiration settings. Required (non-null) when `type`
is
`FIXED_DURATION`; must be null/omitted otherwise.
oneOf:
- $ref: '#/components/schemas/TierStructureExpirationFixedDurationUpsert'
- type: 'null'
calendar_expiration:
description: |-
Calendar expiration settings. Required (non-null) when `type` is
`CALENDAR_EXPIRATION`; must be null/omitted otherwise.
oneOf:
- $ref: >-
#/components/schemas/TierStructureExpirationCalendarExpirationUpsert
- type: 'null'
sliding_expiration:
description: |-
Sliding expiration settings. Required (non-null) when `type` is
`SLIDING_EXPIRATION`; must be null/omitted otherwise.
oneOf:
- $ref: >-
#/components/schemas/TierStructureExpirationSlidingExpirationUpsert
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_RETENTION
then:
properties:
fixed_duration:
type: 'null'
calendar_expiration:
type: 'null'
sliding_expiration:
type: 'null'
- if:
properties:
type:
const: FIXED_DURATION
then:
required:
- fixed_duration
properties:
fixed_duration:
$ref: >-
#/components/schemas/TierStructureExpirationFixedDurationUpsert
calendar_expiration:
type: 'null'
sliding_expiration:
type: 'null'
- if:
properties:
type:
const: CALENDAR_EXPIRATION
then:
required:
- calendar_expiration
properties:
fixed_duration:
type: 'null'
calendar_expiration:
$ref: >-
#/components/schemas/TierStructureExpirationCalendarExpirationUpsert
sliding_expiration:
type: 'null'
- if:
properties:
type:
const: SLIDING_EXPIRATION
then:
required:
- sliding_expiration
properties:
fixed_duration:
type: 'null'
calendar_expiration:
type: 'null'
sliding_expiration:
$ref: >-
#/components/schemas/TierStructureExpirationSlidingExpirationUpsert
TierStructureDowngradeUpsert:
type: object
description: >-
Downgrade settings. Controls how members are moved to lower tiers on
expiration.
When `type` is `NO_DOWNGRADE`, `grace_period` must be null/omitted.
properties:
type:
type: string
enum:
- MULTI_LEVEL
- SINGLE_LEVEL
- NO_DOWNGRADE
description: >-
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:
description: >-
Grace period before the downgrade takes effect. Must be null/omitted
when
`type` is `NO_DOWNGRADE`.
oneOf:
- $ref: '#/components/schemas/TierStructureDowngradeGracePeriodUpsert'
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_DOWNGRADE
then:
properties:
grace_period:
type: 'null'
TierStructurePointBalance:
type: object
description: Point balance tracking settings.
properties:
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition whose point balance is
tracked.
TierStructurePointEarned:
type: object
description: Points earned tracking settings.
properties:
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique identifier of the card definition whose earned points are
tracked.
period:
$ref: '#/components/schemas/TierStructurePointEarnedPeriod'
description: Tracking period during which earned points are accumulated.
type:
type: string
enum:
- IMMEDIATELY
- NEXT_TRACKING_PERIOD
description: When a tier change resulting from earned points takes effect.
TierStructureExpiration:
type: object
description: >-
Tier membership expiration settings. Only the sub-object matching `type`
is
present; the others are omitted.
properties:
type:
type: string
enum:
- NO_RETENTION
- SLIDING_EXPIRATION
- FIXED_DURATION
- CALENDAR_EXPIRATION
description: Expiration model for tier membership.
fixed_duration:
$ref: '#/components/schemas/TierStructureExpirationFixedDuration'
description: >-
Fixed duration settings. Present only when `type` is
`FIXED_DURATION`.
calendar_expiration:
$ref: '#/components/schemas/TierStructureExpirationCalendarExpiration'
description: >-
Calendar expiration settings. Present only when `type` is
`CALENDAR_EXPIRATION`.
sliding_expiration:
$ref: '#/components/schemas/TierStructureExpirationSlidingExpiration'
description: >-
Sliding expiration settings. Present only when `type` is
`SLIDING_EXPIRATION`.
TierStructureDowngrade:
type: object
description: Downgrade settings.
properties:
type:
type: string
enum:
- MULTI_LEVEL
- SINGLE_LEVEL
- NO_DOWNGRADE
description: Downgrade model.
grace_period:
$ref: '#/components/schemas/TierStructureDowngradeGracePeriod'
description: >-
Grace period before the downgrade takes effect. Omitted when not
configured.
TierStructurePointEarnedPeriodUpsert:
type: object
description: >-
Points earned tracking period. The maximum `value` depends on `unit`: 90
for
`DAY`, 52 for `WEEK`, 12 for `MONTH`, 5 for `YEAR`.
properties:
value:
type: integer
minimum: 1
description: >-
Length of the tracking period, expressed in `unit` units. Minimum 1.
Maximum
depends on `unit` (DAY: 90, WEEK: 52, MONTH: 12, YEAR: 5).
unit:
type: string
enum:
- DAY
- WEEK
- MONTH
- YEAR
description: Unit of the tracking period.
additionalProperties: false
allOf:
- required:
- value
- unit
- if:
properties:
unit:
const: DAY
then:
properties:
value:
type: integer
minimum: 1
maximum: 90
- if:
properties:
unit:
const: WEEK
then:
properties:
value:
type: integer
minimum: 1
maximum: 52
- if:
properties:
unit:
const: MONTH
then:
properties:
value:
type: integer
minimum: 1
maximum: 12
- if:
properties:
unit:
const: YEAR
then:
properties:
value:
type: integer
minimum: 1
maximum: 5
TierStructureExpirationFixedDurationUpsert:
type: object
description: >-
Fixed duration expiration settings. Tier membership expires after a
fixed period.
properties:
period:
$ref: >-
#/components/schemas/TierStructureExpirationFixedDurationPeriodUpsert
description: Duration after which the tier membership expires.
required:
- period
additionalProperties: false
TierStructureExpirationCalendarExpirationUpsert:
type: object
description: >-
Calendar expiration settings. Tier membership expires on fixed calendar
dates.
properties:
calendar_dates:
type: array
minItems: 1
maxItems: 20
description: >-
Calendar dates (day + month) on which tier membership expires. 1-20
items.
items:
$ref: '#/components/schemas/TierStructureExpirationCalendarDateUpsert'
required:
- calendar_dates
additionalProperties: false
TierStructureExpirationSlidingExpirationUpsert:
type: object
description: >-
Sliding expiration settings. Tier membership expiration slides forward
on the
configured member activities.
properties:
earning_activity:
type: boolean
description: Whether point earning activity extends the tier membership.
spending_activity:
type: boolean
description: Whether point spending activity extends the tier membership.
custom_activity:
type: boolean
description: Whether custom activities extend the tier membership.
custom_activity_types:
type: array
maxItems: 10
uniqueItems: true
description: >-
Custom activity type names that extend the tier membership. Up to 10
unique
items. Defaults to an empty array when omitted.
items:
type: string
minLength: 1
description: Custom activity type name.
period:
description: >-
Sliding period after the last qualifying activity. Required (may be
null).
oneOf:
- $ref: >-
#/components/schemas/TierStructureExpirationSlidingExpirationPeriodUpsert
- type: 'null'
required:
- period
additionalProperties: false
TierStructureDowngradeGracePeriodUpsert:
type: object
description: Downgrade grace period.
properties:
value:
type: integer
minimum: 1
description: Length of the grace period, expressed in `unit` units. Minimum 1.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Unit of the grace period.
round_up:
type: boolean
description: Whether the grace period end is rounded up to the end of the unit.
required:
- value
- unit
additionalProperties: false
TierStructurePointEarnedPeriod:
type: object
description: Points earned tracking period.
properties:
value:
type: integer
description: Length of the tracking period, expressed in `unit` units.
unit:
type: string
enum:
- DAY
- WEEK
- MONTH
- YEAR
description: Unit of the tracking period.
TierStructureExpirationFixedDuration:
type: object
description: Fixed duration expiration settings.
properties:
period:
$ref: '#/components/schemas/TierStructureExpirationPeriod'
description: Duration after which the tier membership expires.
TierStructureExpirationCalendarExpiration:
type: object
description: Calendar expiration settings.
properties:
calendar_dates:
type: array
description: Calendar dates on which tier membership expires.
items:
$ref: '#/components/schemas/TierStructureExpirationCalendarDate'
TierStructureExpirationSlidingExpiration:
type: object
description: Sliding expiration settings.
properties:
earning_activity:
type: boolean
description: Whether point earning activity extends the tier membership.
spending_activity:
type: boolean
description: Whether point spending activity extends the tier membership.
custom_activity:
type: boolean
description: Whether custom activities extend the tier membership.
custom_activity_types:
type: array
description: Custom activity type names that extend the tier membership.
items:
type: string
description: Custom activity type name.
period:
$ref: '#/components/schemas/TierStructureExpirationPeriod'
description: Sliding period after the last qualifying activity.
TierStructureDowngradeGracePeriod:
type: object
description: Downgrade grace period.
properties:
value:
type: integer
description: Length of the grace period, expressed in `unit` units.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Unit of the grace period.
round_up:
type: boolean
description: Whether the grace period end is rounded up to the end of the unit.
TierStructureExpirationFixedDurationPeriodUpsert:
type: object
description: Fixed duration expiration period.
properties:
value:
type: integer
minimum: 1
description: >-
Length of the expiration period, expressed in `unit` units. Minimum
1.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Unit of the expiration period.
required:
- value
- unit
additionalProperties: false
TierStructureExpirationCalendarDateUpsert:
type: object
description: >-
A recurring calendar date. The maximum `day` depends on `month`: 29 for
February
(month 2), 30 for April/June/September/November (months 4, 6, 9, 11),
and 31 for
the remaining months.
properties:
day:
type: integer
minimum: 1
maximum: 31
description: >-
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:
type: integer
minimum: 1
maximum: 12
description: Month of the year (1-12).
additionalProperties: false
allOf:
- required:
- day
- month
- if:
properties:
month:
const: 2
then:
properties:
day:
type: integer
minimum: 1
maximum: 29
- if:
properties:
month:
enum:
- 4
- 6
- 9
- 11
then:
properties:
day:
type: integer
minimum: 1
maximum: 30
- if:
properties:
month:
enum:
- 1
- 3
- 5
- 7
- 8
- 10
- 12
then:
properties:
day:
type: integer
minimum: 1
maximum: 31
TierStructureExpirationSlidingExpirationPeriodUpsert:
type: object
description: Sliding expiration period.
properties:
value:
type: integer
minimum: 1
description: Length of the sliding period, expressed in `unit` units. Minimum 1.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Unit of the sliding period.
required:
- value
- unit
additionalProperties: false
TierStructureExpirationPeriod:
type: object
description: |-
Expiration period. The same shape is used for fixed duration and sliding
expiration periods.
properties:
value:
type: integer
description: Length of the period, expressed in `unit` units.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Unit of the period.
TierStructureExpirationCalendarDate:
type: object
description: A recurring calendar date.
properties:
day:
type: integer
minimum: 1
maximum: 31
description: Day of the month (1-31).
month:
type: integer
minimum: 1
maximum: 12
description: Month of the year (1-12).
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````