> ## Documentation Index > Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt > Use this file to discover all available pages before exploring further. # Create 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 subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager. Creates a new tier structure. Depending on `type`, either `point_balance` (for `POINT_BALANCE`) or `point_earned` (for `POINT_EARNED`) is required and the other must be null/omitted. If `expiration` is omitted it defaults to `{ "type": "NO_EXPIRATION" }`; if `downgrade` is omitted it defaults to `{ "type": "NO_DOWNGRADE" }`; if `status` is omitted it defaults to `DRAFT`. ## OpenAPI ````yaml /openapi/loyalties-v2.json post /v2/loyalties/tier-structures 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: - bearerAuth: [] X-App-Id: [] X-App-Token: [] 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), 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: post: tags: - Tier Structures summary: Create 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 subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager. Creates a new tier structure. Depending on `type`, either `point_balance` (for `POINT_BALANCE`) or `point_earned` (for `POINT_EARNED`) is required and the other must be null/omitted. If `expiration` is omitted it defaults to `{ "type": "NO_EXPIRATION" }`; if `downgrade` is omitted it defaults to `{ "type": "NO_DOWNGRADE" }`; if `status` is omitted it defaults to `DRAFT`. operationId: createTierStructure requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TierStructureCreateRequest' responses: '200': description: The created 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: TierStructureCreateRequest: type: object description: > Request body for creating a tier structure. No additional properties are allowed. properties: name: type: string minLength: 1 maxLength: 200 description: Display name of the tier structure. Required. type: type: string enum: - POINT_BALANCE - POINT_EARNED description: > Tier qualification tracking model. `POINT_BALANCE` qualifies members by their current point balance; `POINT_EARNED` qualifies members by points earned within a tracking period. Required. point_balance: description: | Point balance tracking settings. Required (non-null) when `type` is `POINT_BALANCE`; must be null/omitted when `type` is `POINT_EARNED`. oneOf: - $ref: '#/components/schemas/TierStructurePointBalanceUpsert' - type: 'null' point_earned: description: | Points earned tracking settings. Required (non-null) when `type` is `POINT_EARNED`; must be null/omitted when `type` is `POINT_BALANCE`. oneOf: - $ref: '#/components/schemas/TierStructurePointEarnedUpsert' - type: 'null' expiration: description: | Tier membership expiration settings. If omitted, defaults to `{ "type": "NO_EXPIRATION" }`. oneOf: - $ref: '#/components/schemas/TierStructureExpirationUpsert' - type: 'null' downgrade: description: > Downgrade behavior applied when tier membership expires. If omitted, defaults to `{ "type": "NO_DOWNGRADE" }`. oneOf: - $ref: '#/components/schemas/TierStructureDowngradeUpsert' - type: 'null' metadata: description: Free-form key/value object holding custom attributes. oneOf: - type: object - type: 'null' status: type: string enum: - DRAFT - ACTIVE description: >- Initial status of the tier structure. Defaults to `DRAFT` when omitted. additionalProperties: false allOf: - required: - name - type - if: properties: type: const: POINT_EARNED then: required: - point_earned properties: point_earned: $ref: '#/components/schemas/TierStructurePointEarnedUpsert' point_balance: type: 'null' - if: properties: type: const: POINT_BALANCE 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: Identifier of the request 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: 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: 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_EXPIRATION - 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_EXPIRATION 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: 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: 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_EXPIRATION - 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: bearerAuth: type: http scheme: bearer bearerFormat: JWT X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header ````