List tier structures

curl --request GET \
  --url {protocol}://{host}/v2/loyalties/tier-structures \
  --header 'Authorization: Bearer <token>' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>'

{
  "data": [
    {
      "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
        }
      }
    }
  ],
  "cursor": {
    "next": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "object": "<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>"
}

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

List tier structures

⚠️ 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.

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.

GET

loyalties

tier-structures

Error

A valid request URL is required to generate request examples

{
  "data": [
    {
      "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
        }
      }
    }
  ],
  "cursor": {
    "next": "<string>",
    "expires_at": "2023-11-07T05:31:56Z"
  },
  "object": "<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>"
}

{
  "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

Query Parameters

limit

integer

default:10

Maximum number of items returned per page. An integer between 1 and 100. Defaults to 10.

Required range: 1 <= x <= 100

order

Sort order. A single field name or an array of field names; prefix a field with - for descending order. Default is -created_at. The same field must not be requested in both ascending and descending direction at once.

Available options:

-created_at,

created_at,

name,

-name,

type,

-type,

status,

-status

cursor

string

Pagination cursor returned in the cursor.next field of a previous response. Must match the tier structures cursor id format.

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

filters

object

Field-specific filter conditions, passed as a deep object (e.g. filters[status][conditions][$is]=ACTIVE).

Filters for the tier structures list. Each field accepts a conditions object; each filter field may also be null.

Show child attributes

Response

Paginated list of tier structures.

Cursor-paginated list of tier structures.

data

object[]

required

Tier structures on the current page.

Show child attributes

cursor

object | null

required

Pagination cursor for fetching the next page, or null when there are no more results.

Show child attributes

object

string

required

Object type discriminator. Always list.

Allowed value: "list"

Last modified on July 10, 2026

List earning rule activities Create tier structure

⌘I