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

# Create tier

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

<Warning>

<Badge color="yellow">BETA endpoint</Badge>

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](https://www.voucherify.io/contact-support) or your Technical Account Manager.

</Warning>

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 — 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 — 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 — 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 — 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, required — Last update timestamp (ISO 8601), or null if never updated.
  - `object` string, 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-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/versions/4982266e0494/schema)