---
title: "Create tier"
method: POST
path: "/v2/loyalties/tier-structures/{tierStructureId}/tiers"
tags: ["Tier Structures"]
---

# Create tier

`POST /v2/loyalties/tier-structures/{tierStructureId}/tiers`

<Info>

<Badge color="gray">Documentation in progress</Badge>

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.

</Info>

Creates a tier within the tier structure. If `downgrade` is omitted it defaults to
`{ "type": "INHERIT" }`. A tier structure can hold at most 10 tiers.

## Path parameters

- `id` string, required

## Request body

- TierCreateRequest — Request body for creating a tier. No additional properties are allowed.
  - `name` string, required — Display name of the tier. Required.
  - `qualification_rules` TierQualificationRulesUpsert, required — 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.
    - `type` 'POINTS' | 'POINTS_AND_SEGMENT', required — Qualification model. `POINTS` qualifies by point thresholds only; `POINTS_AND_SEGMENT` additionally requires membership in a customer segment. Required.
    - `points` TierQualificationRulesPointsUpsert — Point thresholds for tier qualification. Values must be non-negative numbers between 0 and 1,000,000,000.
      - `min_value` number, required — Minimum number of points required to qualify for the tier. Required.
      - `max_value` number — Optional upper bound of points for the tier.
    - `segment` TierQualificationRulesSegmentUpsert — Customer segment reference for tier qualification.
      - `id` string, required — Unique identifier of the customer segment.
  - `downgrade` TierDowngradeUpsert — Tier-level downgrade behavior.
    - `type` 'INHERIT' | 'NO_DOWNGRADE', required — `INHERIT` uses the parent tier structure downgrade settings; `NO_DOWNGRADE` disables downgrades from this tier. Required.
  - `metadata` object, nullable — Free-form key/value object holding custom attributes.

## Response `200`

The created tier.

- Tier — Tier resource.
  - `id` string, required — Unique tier identifier.
  - `tier_structure_id` string, required — Unique identifier of the parent tier structure.
  - `name` string, required — Display name of the tier.
  - `qualification_rules` TierQualificationRules — Tier qualification rules.
    - `type` 'POINTS' | 'POINTS_AND_SEGMENT' — Qualification model.
    - `points` TierQualificationRulesPoints — Point thresholds for tier qualification.
      - `min_value` number — Minimum number of points required to qualify for the tier.
      - `max_value` number — Optional upper bound of points for the tier. Omitted when not set.
    - `segment` TierQualificationRulesSegment — Customer segment reference.
      - `id` string — Unique identifier of the customer segment.
  - `downgrade` TierDowngrade, required — Tier-level downgrade behavior.
    - `type` 'INHERIT' | 'NO_DOWNGRADE' — Downgrade model. Omitted when the tier has no downgrade configured.
  - `metadata` object, required — Free-form key/value object holding custom attributes. Defaults to `{}`.
  - `created_at` string, date-time, required — Creation timestamp (ISO 8601).
  - `updated_at` string, date-time, nullable, required — Last update timestamp (ISO 8601), or `null` if never updated.
  - `object` 'tier', required — Object type discriminator. Always `tier`.

## Other responses

- `400` — Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state.
- `404` — Resource not found.
- `409` — Conflict - e.g. duplicate resource or invalid state transition.
- `500` — Internal server error.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/versions/69be73b5cff0/schema)