> ## 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.
# List tier structures
>
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 cursor-paginated list of tier structures. The same field cannot be
requested in both ascending and descending order at once. Default order is
`-created_at`.
## OpenAPI
````yaml /openapi/loyalties-v2.json get /v2/loyalties/tier-structures
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:
get:
tags:
- Tier Structures
summary: List tier structures
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 cursor-paginated list of tier structures. The same field
cannot be
requested in both ascending and descending order at once. Default order
is
`-created_at`.
operationId: listTierStructures
parameters:
- name: limit
in: query
required: false
description: >-
Limits the page size to an integer from 1 to 100. Defaults to 10. A
numeric string is accepted and rounded to the nearest integer.
schema:
type:
- number
- string
- 'null'
minimum: 1
maximum: 100
default: 10
- name: order
in: query
required: false
description: >-
Orders the results. Accepts one value or an array. Prefix a field
with `-` for descending order. Defaults to `-created_at`. The same
field cannot be used in both directions. Rows with the same sort
value are then ordered by `id` ascending.
schema:
oneOf:
- type: string
enum:
- '-created_at'
- created_at
- name
- '-name'
- type
- '-type'
- status
- '-status'
- type: array
items:
type: string
enum:
- '-created_at'
- created_at
- name
- '-name'
- type
- '-type'
- status
- '-status'
- type: 'null'
- name: cursor
in: query
required: false
description: >-
Continues pagination. Pass the `cursor.next` value from a previous
response. Format `lcrsts_[a-f0-9]+`. The cursor matches the filters
and order of that response.
schema:
type:
- string
- 'null'
pattern: ^lcrsts_[a-f0-9]+$
- name: filters
in: query
required: false
style: deepObject
explode: true
description: >-
Filters the results. Pass a deep object, for example
`filters[status][conditions][$is]=ACTIVE`. Fields combine through
`junction`, which defaults to `AND`. Omit `filters` to apply no
field filter.
schema:
oneOf:
- $ref: '#/components/schemas/LoyaltiesTierStructuresListRequestQuery'
- type: 'null'
responses:
'200':
description: Paginated list of tier structures.
content:
application/json:
schema:
$ref: '#/components/schemas/V2LoyaltiesTierStructuresListResponseBody'
'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:
LoyaltiesTierStructuresListRequestQuery:
type: object
description: Request query schema for **GET** `/v2/loyalties/tier-structures`.
properties:
junction:
description: >-
Joins the field filters. Allowed values are `AND` and `OR`. Defaults
to `AND`.
oneOf:
- type: string
enum:
- AND
- OR
- type: 'null'
id:
description: Filters by tier structure id. Format `lts_[a-f0-9]+`.
oneOf:
- $ref: '#/components/schemas/LoyaltiesTierStructuresListRequestQueryId'
- type: 'null'
name:
description: Filters by tier structure name.
oneOf:
- $ref: '#/components/schemas/LoyaltiesTierStructuresListRequestQueryName'
- type: 'null'
type:
description: >-
Filters by tier structure type. Allowed values: `POINT_BALANCE`,
`POINT_EARNED`.
oneOf:
- $ref: '#/components/schemas/LoyaltiesTierStructuresListRequestQueryType'
- type: 'null'
status:
description: >-
Filters by tier structure status. Allowed values: `DRAFT`, `ACTIVE`,
`INACTIVE`, `DELETED`.
oneOf:
- $ref: >-
#/components/schemas/LoyaltiesTierStructuresListRequestQueryStatus
- type: 'null'
created_at:
description: Filters by creation date.
oneOf:
- $ref: '#/components/schemas/TierStructureFilterDateField'
- type: 'null'
additionalProperties: false
title: Loyalties Tier Structures List Request Query
V2LoyaltiesTierStructuresListResponseBody:
title: V2 Loyalties Tier Structures List Response Body
type: object
description: Response body schema for **GET** `/v2/loyalties/tier-structures`.
allOf:
- $ref: '#/components/schemas/TierStructureListResponse'
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.
LoyaltiesTierStructuresListRequestQueryId:
type: object
description: >-
ID field filter for tier structure ids. Allowed conditions: `$is`,
`$is_not`,
`$in`, `$not_in`. Each condition accepts a single string or an array of
strings
matching `^lts_[a-f0-9]+$`.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
description: Condition operators applied to the field.
properties:
$is:
description: >-
Matches one value. A string or a one-element array. Format
`lts_[a-f0-9]+`.
oneOf:
- type: string
pattern: ^lts_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lts_[a-f0-9]+$
minItems: 1
maxItems: 1
- type: 'null'
$is_not:
description: >-
Excludes one value. A string or a one-element array. Format
`lts_[a-f0-9]+`.
oneOf:
- type: string
pattern: ^lts_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lts_[a-f0-9]+$
minItems: 1
maxItems: 1
- type: 'null'
$in:
description: >-
Matches any of the values. A string or an array of 1 to 100
values. Format `lts_[a-f0-9]+`.
oneOf:
- type: string
pattern: ^lts_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lts_[a-f0-9]+$
minItems: 1
maxItems: 100
- type: 'null'
$not_in:
description: >-
Excludes any of the values. A string or an array of 1 to 100
values. Format `lts_[a-f0-9]+`.
oneOf:
- type: string
pattern: ^lts_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lts_[a-f0-9]+$
minItems: 1
maxItems: 100
- type: 'null'
required:
- conditions
additionalProperties: false
LoyaltiesTierStructuresListRequestQueryName:
type: object
description: >-
String field filter. Allowed conditions: `$is`, `$is_not`, `$contains`,
`$not_contain`, `$starts_with`, `$ends_with`, `$in`, `$not_in`,
`$has_value`,
`$is_unknown`. Each condition accepts a single string or an array of
strings.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
description: Condition operators applied to the field.
properties:
$is:
description: Matches one value. A string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$is_not:
description: Excludes one value. A string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$contains:
description: >-
Matches when the value contains the substring. A string or a
one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$not_contain:
description: >-
Excludes values that contain the substring. A string or a
one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$starts_with:
description: >-
Matches when the value starts with the prefix. A string or a
one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$ends_with:
description: >-
Matches when the value ends with the suffix. A string or a
one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$in:
description: >-
Matches any of the values. A string or an array of 1 to 10
values.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 10
- type: 'null'
$not_in:
description: >-
Excludes any of the values. A string or an array of 1 to 10
values.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 10
- type: 'null'
$has_value:
description: Matches when the field is set. The condition value is ignored.
oneOf:
- type: string
- type: array
maxItems: 1
- type: 'null'
$is_unknown:
description: >-
Matches when the field is not set. The condition value is
ignored.
oneOf:
- type: string
- type: array
maxItems: 1
- type: 'null'
required:
- conditions
additionalProperties: false
LoyaltiesTierStructuresListRequestQueryType:
type: object
description: >-
Enum field filter for tier structure `type`. Allowed conditions: `$is`,
`$is_not`,
`$in`, `$not_in`. Allowed values: `POINT_BALANCE`, `POINT_EARNED`.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
description: Condition operators applied to the field.
properties:
$is:
description: Matches one value. A string or a one-element array.
oneOf:
- type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: array
minItems: 1
maxItems: 1
items:
type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: 'null'
$is_not:
description: Excludes one value. A string or a one-element array.
oneOf:
- type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: array
minItems: 1
maxItems: 1
items:
type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: 'null'
$in:
description: >-
Matches any of the values. A string or an array of 1 to 10
values.
oneOf:
- type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: array
minItems: 1
maxItems: 10
items:
type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: 'null'
$not_in:
description: >-
Excludes any of the values. A string or an array of 1 to 10
values.
oneOf:
- type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: array
minItems: 1
maxItems: 10
items:
type: string
enum:
- POINT_BALANCE
- POINT_EARNED
- type: 'null'
required:
- conditions
additionalProperties: false
LoyaltiesTierStructuresListRequestQueryStatus:
type: object
description: >-
Enum field filter for tier structure `status`. Allowed conditions:
`$is`,
`$is_not`, `$in`, `$not_in`. Allowed values: `DRAFT`, `ACTIVE`,
`INACTIVE`,
`DELETED`.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
description: Condition operators applied to the field.
properties:
$is:
description: Matches one value. A string or a one-element array.
oneOf:
- type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: array
minItems: 1
maxItems: 1
items:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: 'null'
$is_not:
description: Excludes one value. A string or a one-element array.
oneOf:
- type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: array
minItems: 1
maxItems: 1
items:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: 'null'
$in:
description: >-
Matches any of the values. A string or an array of 1 to 10
values.
oneOf:
- type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: array
minItems: 1
maxItems: 10
items:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: 'null'
$not_in:
description: >-
Excludes any of the values. A string or an array of 1 to 10
values.
oneOf:
- type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: array
minItems: 1
maxItems: 10
items:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
- type: 'null'
required:
- conditions
additionalProperties: false
TierStructureFilterDateField:
type: object
description: >-
Date field filter. Allowed conditions: `$before`, `$after`, `$is`,
`$more_than`,
`$less_than`, `$has_value`, `$is_unknown`. `$before`/`$after` accept
valid date
strings; `$is`/`$more_than`/`$less_than` accept non-negative integer
values.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
description: Condition operators applied to the field.
properties:
$before:
description: >-
Matches dates before the given value. An ISO 8601 date-time, as
a string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$after:
description: >-
Matches dates after the given value. An ISO 8601 date-time, as a
string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$is:
description: >-
Matches a date exactly the given number of days ago. A
non-negative integer, as a string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$more_than:
description: >-
Matches dates more than the given number of days ago. A
non-negative integer, as a string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$less_than:
description: >-
Matches dates less than the given number of days ago. A
non-negative integer, as a string or a one-element array.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$has_value:
description: Matches when the field is set. The condition value is ignored.
oneOf:
- type: string
- type: array
maxItems: 1
- type: 'null'
$is_unknown:
description: >-
Matches when the field is not set. The condition value is
ignored.
oneOf:
- type: string
- type: array
maxItems: 1
- type: 'null'
required:
- conditions
additionalProperties: false
TierStructureListResponse:
type: object
description: Cursor-paginated list of tier structures.
properties:
data:
type: array
description: Tier structures on the current page.
items:
$ref: '#/components/schemas/TierStructure'
cursor:
description: >-
Pagination cursor for fetching the next page, or `null` when there
are no more
results.
oneOf:
- type: object
properties:
next:
type: string
pattern: ^lcrsts_[a-f0-9]+$
description: >-
Cursor id to pass as the `cursor` query parameter for the
next page.
expires_at:
type: string
format: date-time
description: Timestamp after which the cursor expires (ISO 8601).
- type: 'null'
object:
type: string
const: list
description: Object type discriminator. Always `list`.
required:
- data
- cursor
- object
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.