> ## 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.
# Get tier structure
>
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.
Returns a single tier structure by its ID.
## OpenAPI
````yaml /openapi/loyalties-v2.json get /v2/loyalties/tier-structures/{tierStructureId}
openapi: 3.1.0
info:
title: Voucherify API - Loyalty v2
version: v2018-08-01
description: >-
Voucherify promotion engine REST API. Please see
https://docs.voucherify.io/docs for more details.
contact:
name: Voucherify Team
url: https://www.voucherify.io/contact-support
email: support@voucherify.io
termsOfService: https://www.voucherify.io/legal/subscription-agreement
license:
name: MIT
url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE
servers:
- url: https://{cluster}.voucherify.io
description: Base URL
variables:
cluster:
default: api
enum:
- api
- us1.api
- as1.api
- download
- us1.download
- as1.download
security: []
paths:
/v2/loyalties/tier-structures/{tierStructureId}:
parameters:
- name: tierStructureId
in: path
required: true
description: Unique tier structure identifier.
schema:
type: string
pattern: ^lts_[a-f0-9]+$
get:
tags:
- Tier Structures
summary: Get tier structure
description: >-
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.
Returns a single tier structure by its ID.
operationId: getTierStructure
responses:
'200':
description: The tier structure.
content:
application/json:
schema:
$ref: '#/components/schemas/V2LoyaltiesTierStructuresGetResponseBody'
'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'
examples:
Internal server error:
value:
code: 500
key: api_error
message: >-
Something went wrong. Don't worry, your campaigns are
still safe and the Voucherify Team has been notified.
Check out our Help Center and forums for help, or head
back to home.
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
components:
schemas:
V2LoyaltiesTierStructuresGetResponseBody:
title: V2 Loyalties Tier Structures Get Response Body
type: object
description: >-
Response body schema for **GET**
`/v2/loyalties/tier-structures/{tierStructureId}`.
allOf:
- $ref: '#/components/schemas/TierStructure'
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.
TierStructure:
description: Tier structure resource.
allOf:
- $ref: '#/components/schemas/TierMetadataBase'
- type: object
properties:
id:
type: string
pattern: ^lts_[a-f0-9]+$
description: Unique tier structure identifier.
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/LoyaltyV2ActivityTierStructurePointBalance'
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.
status:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
description: Current lifecycle status of the tier structure.
object:
type: string
const: tier_structure
description: Object type discriminator. Always `tier_structure`.
required:
- id
- name
- type
- expiration
- downgrade
- status
- object
TierMetadataBase:
type: object
properties:
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.
required:
- metadata
- created_at
- updated_at
LoyaltyV2ActivityTierStructurePointBalance:
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/LoyaltyV2ActivityTierStructurePointEarnedPeriod'
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/LoyaltyV2ActivityTierStructureDowngradeGracePeriod
description: >-
Grace period before the downgrade takes effect. Omitted when not
configured.
LoyaltyV2ActivityTierStructurePointEarnedPeriod:
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/LoyaltyV2ActivityTierStructureExpirationPeriod'
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/LoyaltyV2ActivityTierStructureExpirationCalendarDate
TierStructureExpirationSlidingExpiration:
description: Sliding expiration settings.
allOf:
- $ref: '#/components/schemas/TierStructureSlidingExpirationActivityBase'
- type: object
properties:
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/LoyaltyV2ActivityTierStructureExpirationPeriod
description: Sliding period after the last qualifying activity.
LoyaltyV2ActivityTierStructureDowngradeGracePeriod:
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.
LoyaltyV2ActivityTierStructureExpirationPeriod:
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.
LoyaltyV2ActivityTierStructureExpirationCalendarDate:
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).
TierStructureSlidingExpirationActivityBase:
type: object
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.
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.