> ## 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
>
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.
Creates a tier within the tier structure. If `downgrade` is omitted it defaults to
`{ "type": "INHERIT" }`. A tier structure can hold at most 100 tiers.
## OpenAPI
````yaml /openapi/loyalties-v2.json post /v2/loyalties/tier-structures/{tierStructureId}/tiers
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}/tiers:
parameters:
- name: tierStructureId
in: path
required: true
description: Identifies the tier structure. Format `lts_[a-f0-9]+`.
schema:
type: string
pattern: ^lts_[a-f0-9]+$
post:
tags:
- Tier Structures
summary: Create tier
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.
Creates a tier within the tier structure. If `downgrade` is omitted it
defaults to
`{ "type": "INHERIT" }`. A tier structure can hold at most 100 tiers.
operationId: createTier
requestBody:
required: true
content:
application/json:
schema:
$ref: >-
#/components/schemas/V2LoyaltiesTierStructuresTiersCreateRequestBody
responses:
'200':
description: The created tier.
content:
application/json:
schema:
$ref: >-
#/components/schemas/V2LoyaltiesTierStructuresTiersCreateResponseBody
'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:
V2LoyaltiesTierStructuresTiersCreateRequestBody:
title: V2 Loyalties Tier Structures Tiers Create Request Body
type: object
description: >-
Request body schema for **POST**
`/v2/loyalties/tier-structures/{tierStructureId}/tiers`.
allOf:
- $ref: '#/components/schemas/TierCreateRequest'
V2LoyaltiesTierStructuresTiersCreateResponseBody:
title: V2 Loyalties Tier Structures Tiers Create Response Body
type: object
description: >-
Response body schema for **POST**
`/v2/loyalties/tier-structures/{tierStructureId}/tiers`.
allOf:
- $ref: '#/components/schemas/Tier'
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.
TierCreateRequest:
type: object
description: Request body for creating a tier. No additional properties are allowed.
properties:
name:
type: string
minLength: 1
maxLength: 200
description: Display name of the tier. Required.
qualification_rules:
description: Rules determining which members qualify for this tier. Required.
oneOf:
- $ref: '#/components/schemas/TierQualificationRulesUpsert'
downgrade:
description: >-
Tier-level downgrade behavior. If omitted, defaults to `{ "type":
"INHERIT" }`
(inherits the tier structure downgrade settings).
oneOf:
- $ref: '#/components/schemas/TierDowngradeUpsert'
- type: 'null'
metadata:
description: Free-form key/value object holding custom attributes.
oneOf:
- type: object
- type: 'null'
required:
- name
- qualification_rules
additionalProperties: false
Tier:
description: Tier resource.
allOf:
- $ref: '#/components/schemas/TierMetadataBase'
- type: object
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/LoyaltyV2ActivityTierDowngrade'
description: >-
Tier-level downgrade behavior. Always present; when the tier has
no downgrade
configured, an empty object (no `type`) is returned.
object:
type: string
const: tier
description: Object type discriminator. Always `tier`.
required:
- id
- tier_structure_id
- name
- downgrade
- object
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
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
TierQualificationRules:
type: object
description: Tier qualification rules.
properties:
type:
type: string
enum:
- POINTS
- POINTS_AND_SEGMENT
description: Qualification model.
points:
$ref: '#/components/schemas/LoyaltyV2ActivityTierQualificationRulesPoints'
description: Point thresholds for the tier. Omitted when not configured.
segment:
$ref: '#/components/schemas/LoyaltyV2ActivityTierQualificationRulesSegment'
description: >-
Customer segment reference. Present only when `type` is
`POINTS_AND_SEGMENT`.
LoyaltyV2ActivityTierDowngrade:
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
LoyaltyV2ActivityTierQualificationRulesPoints:
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.
LoyaltyV2ActivityTierQualificationRulesSegment:
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.