> ## 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
>
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 within the tier structure. All properties are optional. When the
parent tier structure is not in `DRAFT` status, only `name` and `metadata` may be
updated.
## OpenAPI
````yaml /openapi/loyalties-v2.json put /v2/loyalties/tier-structures/{tierStructureId}/tiers/{tierId}
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}/tiers/{tierId}:
put:
tags:
- Tier Structures
summary: Update tier
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 within the tier structure. All properties are optional.
When the
parent tier structure is not in `DRAFT` status, only `name` and
`metadata` may be
updated.
operationId: updateTier
parameters:
- name: id
in: path
required: true
description: Unique tier structure identifier.
schema:
type: string
pattern: ^lts_[a-f0-9]+$
- name: tierId
in: path
required: true
description: Unique tier identifier.
schema:
type: string
pattern: ^lt_[a-f0-9]+$
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TierUpdateRequest'
responses:
'200':
description: The updated tier.
content:
application/json:
schema:
$ref: '#/components/schemas/Tier'
'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:
TierUpdateRequest:
type: object
description: >-
Request body for updating a tier. All properties are optional; no
additional
properties are allowed. When the parent 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.
qualification_rules:
description: Rules determining which members qualify for this tier.
oneOf:
- $ref: '#/components/schemas/TierQualificationRulesUpsert'
- type: 'null'
downgrade:
description: Tier-level downgrade behavior.
oneOf:
- $ref: '#/components/schemas/TierDowngradeUpsert'
- type: 'null'
metadata:
description: Free-form key/value object holding custom attributes.
oneOf:
- type: object
- type: 'null'
additionalProperties: false
Tier:
type: object
description: Tier resource.
properties:
id:
type: string
pattern: ^lt_[a-f0-9]+$
description: Unique tier identifier.
tier_structure_id:
type: string
pattern: ^lts_[a-f0-9]+$
description: Unique identifier of the parent tier structure.
name:
type: string
description: Display name of the tier.
qualification_rules:
$ref: '#/components/schemas/TierQualificationRules'
description: Rules determining which members qualify for this tier.
downgrade:
$ref: '#/components/schemas/TierDowngrade'
description: >-
Tier-level downgrade behavior. Always present; when the tier has no
downgrade
configured, an empty object (no `type`) is returned.
metadata:
type: object
description: >-
Free-form key/value object holding custom attributes. Defaults to
`{}`.
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
description: Object type discriminator. Always `tier`.
required:
- id
- tier_structure_id
- name
- downgrade
- metadata
- 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.
TierQualificationRulesUpsert:
type: object
description: >-
Tier qualification rules. When `type` is `POINTS`, `points` is required
and
`segment` must be null/omitted; when `type` is `POINTS_AND_SEGMENT`,
both `points`
and `segment` are required.
properties:
type:
type: string
enum:
- POINTS
- POINTS_AND_SEGMENT
description: >-
Qualification model. `POINTS` qualifies by point thresholds only;
`POINTS_AND_SEGMENT` additionally requires membership in a customer
segment.
Required.
points:
description: >-
Point thresholds for the tier. Required (non-null) when `type` is
`POINTS`
or `POINTS_AND_SEGMENT`.
oneOf:
- $ref: '#/components/schemas/TierQualificationRulesPointsUpsert'
- type: 'null'
segment:
description: |-
Customer segment reference. Required (non-null) when `type` is
`POINTS_AND_SEGMENT`; must be null/omitted when `type` is `POINTS`.
oneOf:
- $ref: '#/components/schemas/TierQualificationRulesSegmentUpsert'
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: POINTS
then:
required:
- points
properties:
points:
$ref: '#/components/schemas/TierQualificationRulesPointsUpsert'
segment:
type: 'null'
- if:
properties:
type:
const: POINTS_AND_SEGMENT
then:
required:
- points
- segment
properties:
points:
$ref: '#/components/schemas/TierQualificationRulesPointsUpsert'
segment:
$ref: '#/components/schemas/TierQualificationRulesSegmentUpsert'
TierDowngradeUpsert:
type: object
description: Tier-level downgrade behavior.
properties:
type:
type: string
enum:
- INHERIT
- NO_DOWNGRADE
description: >-
`INHERIT` uses the parent tier structure downgrade settings;
`NO_DOWNGRADE`
disables downgrades from this tier. Required.
required:
- type
additionalProperties: false
TierQualificationRules:
type: object
description: Tier qualification rules.
properties:
type:
type: string
enum:
- POINTS
- POINTS_AND_SEGMENT
description: Qualification model.
points:
$ref: '#/components/schemas/TierQualificationRulesPoints'
description: Point thresholds for the tier. Omitted when not configured.
segment:
$ref: '#/components/schemas/TierQualificationRulesSegment'
description: >-
Customer segment reference. Present only when `type` is
`POINTS_AND_SEGMENT`.
TierDowngrade:
type: object
description: Tier-level downgrade behavior.
properties:
type:
type: string
enum:
- INHERIT
- NO_DOWNGRADE
description: Downgrade model. Omitted when the tier has no downgrade configured.
TierQualificationRulesPointsUpsert:
type: object
description: >-
Point thresholds for tier qualification. Values must be non-negative
numbers
between 0 and 1,000,000,000.
properties:
min_value:
type: number
minimum: 0
maximum: 1000000000
description: Minimum number of points required to qualify for the tier. Required.
max_value:
type: number
minimum: 0
maximum: 1000000000
description: Optional upper bound of points for the tier.
required:
- min_value
additionalProperties: false
TierQualificationRulesSegmentUpsert:
type: object
description: Customer segment reference for tier qualification.
properties:
id:
type: string
minLength: 1
description: Unique identifier of the customer segment.
required:
- id
additionalProperties: false
TierQualificationRulesPoints:
type: object
description: Point thresholds for tier qualification.
properties:
min_value:
type: number
description: Minimum number of points required to qualify for the tier.
max_value:
type: number
description: Optional upper bound of points for the tier. Omitted when not set.
TierQualificationRulesSegment:
type: object
description: Customer segment reference.
properties:
id:
type: string
description: Unique identifier of the customer segment.
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
````