Error

A valid request URL is required to generate request examples

{
  "id": "<string>",
  "name": "<string>",
  "expiration": {
    "fixed_duration": {
      "period": {
        "value": 123
      }
    },
    "calendar_expiration": {
      "calendar_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ],
      "period": {
        "value": 123
      }
    }
  },
  "downgrade": {
    "grace_period": {
      "value": 123,
      "round_up": true
    }
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "point_balance": {
    "card_definition_id": "<string>"
  },
  "point_earned": {
    "card_definition_id": "<string>",
    "period": {
      "value": 123
    }
  }
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Create tier structure

⚠️ BETA endpoint

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 or your Technical Account Manager.

Creates a new tier structure. Depending on type, either point_balance (for POINT_BALANCE) or point_earned (for POINT_EARNED) is required and the other must be null/omitted. If expiration is omitted it defaults to { "type": "NO_EXPIRATION" }; if downgrade is omitted it defaults to { "type": "NO_DOWNGRADE" }; if status is omitted it defaults to DRAFT.

POST

loyalties

tier-structures

Create tier structure

curl --request POST \
  --url {protocol}://{host}/v2/loyalties/tier-structures \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "point_balance": {
    "card_definition_id": "<string>"
  },
  "point_earned": {
    "card_definition_id": "<string>",
    "period": {
      "value": 2
    }
  },
  "expiration": {
    "fixed_duration": {
      "period": {
        "value": 2
      }
    },
    "calendar_expiration": {
      "calendar_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "period": {
        "value": 2
      },
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ]
    }
  },
  "downgrade": {
    "grace_period": {
      "value": 2,
      "round_up": true
    }
  },
  "metadata": {}
}
'

{
  "id": "<string>",
  "name": "<string>",
  "expiration": {
    "fixed_duration": {
      "period": {
        "value": 123
      }
    },
    "calendar_expiration": {
      "calendar_dates": [
        {
          "day": 16,
          "month": 6
        }
      ]
    },
    "sliding_expiration": {
      "earning_activity": true,
      "spending_activity": true,
      "custom_activity": true,
      "custom_activity_types": [
        "<string>"
      ],
      "period": {
        "value": 123
      }
    }
  },
  "downgrade": {
    "grace_period": {
      "value": 123,
      "round_up": true
    }
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "point_balance": {
    "card_definition_id": "<string>"
  },
  "point_earned": {
    "card_definition_id": "<string>",
    "period": {
      "value": 123
    }
  }
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id

string

header

required

X-App-Token

string

header

required

Body

application/json

Request body for creating a tier structure. No additional properties are allowed.

name

string

required

Display name of the tier structure. Required.

Required string length: 1 - 200

type

enum<string>

required

Tier qualification tracking model. POINT_BALANCE qualifies members by their current point balance; POINT_EARNED qualifies members by points earned within a tracking period. Required.

Available options:

POINT_BALANCE,

POINT_EARNED

point_balance

object | null

Point balance tracking settings. Required (non-null) when type is POINT_BALANCE; must be null/omitted when type is POINT_EARNED.

Show child attributes

point_earned

object | null

Points earned tracking settings. Required (non-null) when type is POINT_EARNED; must be null/omitted when type is POINT_BALANCE.

Show child attributes

expiration

object | null

Tier membership expiration settings. If omitted, defaults to { "type": "NO_EXPIRATION" }.

Show child attributes

downgrade

object | null

Downgrade behavior applied when tier membership expires. If omitted, defaults to { "type": "NO_DOWNGRADE" }.

Show child attributes

metadata

object | null

Free-form key/value object holding custom attributes.

status

enum<string>

Initial status of the tier structure. Defaults to DRAFT when omitted.

Available options:

DRAFT,

ACTIVE

Response

The created tier structure.

Tier structure resource.

string

required

Unique tier structure identifier.

Pattern: ^lts_[a-f0-9]+$

name

string

required

Display name of the tier structure.

type

enum<string>

required

Tier qualification tracking model.

Available options:

POINT_BALANCE,

POINT_EARNED

expiration

object

required

Tier membership expiration settings.

Show child attributes

downgrade

object

required

Downgrade behavior applied when tier membership expires.

Show child attributes

metadata

object

required

Free-form key/value object holding custom attributes. Defaults to {}.

status

enum<string>

required

Current lifecycle status of the tier structure.

Available options:

DRAFT,

ACTIVE,

INACTIVE,

DELETED

created_at

string<date-time>

required

Creation timestamp (ISO 8601).

updated_at

string<date-time> | null

required

Last update timestamp (ISO 8601), or null if never updated.

object

string

required

Object type discriminator. Always tier_structure.

Allowed value: "tier_structure"

point_balance

object

Point balance tracking settings. Present only when type is POINT_BALANCE; omitted otherwise.

Show child attributes

point_earned

object

Points earned tracking settings. Present only when type is POINT_EARNED; omitted otherwise.

Show child attributes

Last modified on July 10, 2026

List tier structures Get tier structure

⌘I