> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# List member tier transactions
>
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may be 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.
Lists tier transactions (tier joins, upgrades, downgrades, prolongations and exits)
for the given program member, with cursor-based pagination. Supports filtering by
card id and creation date.
## OpenAPI
````yaml /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/tiers/transactions
openapi: 3.1.0
info:
title: Voucherify Loyalty v2 API
version: 2.0.0
description: >-
Complete OpenAPI specification for the Voucherify Loyalty v2 API.
All endpoints require the LOYALTY_V2 feature flag.
Combined from per-domain specs: programs.yaml, members.yaml,
program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
- url: '{protocol}://{host}'
variables:
protocol:
default: https
enum:
- https
- http
host:
default: api.voucherify.io
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
tags:
- name: Programs
description: >-
Loyalty program CRUD, lifecycle management, program-scoped resource
assignments (card definitions, earning rules, rewards, tier structures),
member management (create, list, get, activate, deactivate, delete),
membership retrieval (member + program + cards with tier progress, by
customer ID, customer source ID, or member ID), card operations (points
adjustment, pending points, expiring points, transactions), reward
purchases, and activity history.
- name: Card Definitions
description: >-
CRUD operations, lifecycle management, and activity history for card
definitions. Card definitions describe the configuration for loyalty
cards, including code generation, points expiration, earning/spending
limits, pending points, refunds, and balance settings.
- name: Earning Rules
description: >-
Manage earning rules that define how customers earn points or receive
incentives based on triggers (events, segments, custom events). Includes
CRUD, lifecycle, and activity history.
- name: Tier Structures
description: >-
CRUD operations, lifecycle management, and activity history for tier
structures. Includes nested tier definitions (create, list, update,
delete) within tier structures. Tier structures define the tiering model
for loyalty programs — how members qualify for and move between tiers.
- name: Benefits
description: >-
Manage benefit definitions (fixed points, proportional points, material,
digital). Includes CRUD, lifecycle transitions, and activity history.
- name: Rewards
description: >-
CRUD, lifecycle operations, and activity history for reward definitions.
Rewards can be material (product/SKU) or digital (discount coupons, gift
vouchers).
- name: Examine
description: >-
Evaluation endpoints that estimate earning opportunities and reward
availability for a customer across their loyalty program memberships,
without side effects.
paths:
/v2/loyalties/programs/{programId}/members/{memberId}/tiers/transactions:
get:
tags:
- Programs
summary: List member tier transactions
description: >-
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The
parameters, fields, request and response bodies, and other data may be
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.
Lists tier transactions (tier joins, upgrades, downgrades, prolongations
and exits)
for the given program member, with cursor-based pagination. Supports
filtering by
card id and creation date.
operationId: listMemberTierTransactions
parameters:
- name: programId
in: path
required: true
description: >-
Unique loyalty program identifier (format: `lprg_` followed by
hexadecimal characters).
schema:
type: string
- name: memberId
in: path
required: true
description: Program member ID (format `lmbr_[a-f0-9]+`).
schema:
type: string
pattern: ^lmbr_[a-f0-9]+$
- name: limit
in: query
required: false
description: >-
Maximum number of items to return. An integer between 1 and 100;
numeric strings are also accepted. Defaults to 10.
schema:
type:
- integer
- 'null'
minimum: 1
maximum: 100
default: 10
- name: order
in: query
required: false
description: >-
Sort order. A field name, optionally prefixed with `-` for
descending order. May be provided multiple times (array). The same
field cannot be used in both ascending and descending order at once.
Default: `-created_at`.
schema:
oneOf:
- type: array
items:
type: string
enum:
- '-created_at'
- created_at
- type: string
enum:
- '-created_at'
- created_at
- type: 'null'
- name: cursor
in: query
required: false
description: >-
Pagination cursor returned in the `cursor.next` field of a previous
response (format: `lcrsttx_` followed by hexadecimal characters).
schema:
type:
- string
- 'null'
pattern: ^lcrsttx_[a-f0-9]+$
- name: filters
in: query
required: false
style: deepObject
explode: true
description: >-
Field filters, e.g. `filters[card_id][conditions][$is]=lcrd_...`.
Each field accepts a `conditions` object with condition operators.
schema:
$ref: '#/components/schemas/TierTransactionListFilters'
responses:
'200':
description: Paginated list of tier transactions.
content:
application/json:
schema:
$ref: '#/components/schemas/TierTransactionListResponse'
'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'
components:
schemas:
TierTransactionListFilters:
type: object
description: Filters for listing tier transactions.
properties:
junction:
description: >-
Logical junction between the field filters. Defaults to AND
behavior.
oneOf:
- type: string
enum:
- AND
- OR
- type: 'null'
card_id:
description: Filter by loyalty card id.
oneOf:
- $ref: '#/components/schemas/TierTransactionFilterCardIdConditions'
- type: 'null'
created_at:
description: Filter by creation date.
oneOf:
- $ref: '#/components/schemas/OrderPaymentFilterDateConditions'
- type: 'null'
additionalProperties: false
TierTransactionListResponse:
type: object
description: Paginated list of tier transactions.
properties:
data:
type: array
description: Tier transactions.
items:
$ref: '#/components/schemas/TierTransaction'
cursor:
description: Pagination cursor. `null` when there are no more results.
oneOf:
- type: object
properties:
next:
type: string
description: >-
Cursor to pass as the `cursor` query parameter to fetch the
next page (format `lcrsttx_...`).
expires_at:
type: string
format: date-time
description: Timestamp when the cursor expires.
- type: 'null'
object:
type: string
const: list
description: Object type marker. Always `list`.
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.
TierTransactionFilterCardIdConditions:
type: object
description: >-
ID filter conditions for loyalty card ids. Values must match pattern
`^lcrd_[a-f0-9]+$`. `$is`/`$is_not` accept a single value (string or
1-element array); `$in`/`$not_in` accept a string or an array of 1-100
values.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
properties:
$is:
description: Matches transactions whose card id equals the given value.
oneOf:
- type: string
pattern: ^lcrd_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lcrd_[a-f0-9]+$
minItems: 1
maxItems: 1
- type: 'null'
$is_not:
description: >-
Matches transactions whose card id does not equal the given
value.
oneOf:
- type: string
pattern: ^lcrd_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lcrd_[a-f0-9]+$
minItems: 1
maxItems: 1
- type: 'null'
$in:
description: Matches transactions whose card id is one of the given values.
oneOf:
- type: string
pattern: ^lcrd_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lcrd_[a-f0-9]+$
minItems: 1
maxItems: 100
- type: 'null'
$not_in:
description: >-
Matches transactions whose card id is not one of the given
values.
oneOf:
- type: string
pattern: ^lcrd_[a-f0-9]+$
- type: array
items:
type: string
pattern: ^lcrd_[a-f0-9]+$
minItems: 1
maxItems: 100
- type: 'null'
required:
- conditions
additionalProperties: false
OrderPaymentFilterDateConditions:
type: object
description: >-
Date filter conditions. `$before`/`$after` accept an ISO date-time
string. `$is`/`$more_than`/`$less_than` accept a non-negative integer
number of days ago. `$has_value`/`$is_unknown` accept any single value
and match rows where the field is set / not set. Single values may also
be passed as 1-element arrays.
properties:
conditions:
type: object
minProperties: 1
additionalProperties: false
properties:
$before:
description: Matches rows with the date before the given date-time.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$after:
description: Matches rows with the date after the given date-time.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$is:
description: Matches rows with the date exactly the given number of days ago.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$more_than:
description: >-
Matches rows with the date more than the given number of days
ago.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$less_than:
description: >-
Matches rows with the date less than the given number of days
ago.
oneOf:
- type: string
- type: array
items:
type: string
minItems: 1
maxItems: 1
- type: 'null'
$has_value:
description: Matches rows where the date field is set.
oneOf:
- type: string
- type: array
maxItems: 1
- type: 'null'
$is_unknown:
description: Matches rows where the date field is not set.
oneOf:
- type: string
- type: array
maxItems: 1
- type: 'null'
required:
- conditions
additionalProperties: false
TierTransaction:
type: object
description: A tier transaction. Represents a tier membership change.
properties:
id:
type: string
description: Unique tier transaction identifier (format `lttx_...`).
card_id:
type: string
description: Unique identifier of the related loyalty card (format `lcrd_...`).
program_id:
type: string
description: Unique identifier of the loyalty program (format `lprg_...`).
member_id:
type: string
description: Unique identifier of the program member (format `lmbr_...`).
card_definition_id:
type: string
description: Unique identifier of the card definition (format `lcdef_...`).
tier_structure_id:
type: string
description: Unique identifier of the tier structure (format `lts_...`).
tier_id:
type:
- string
- 'null'
description: Unique identifier of the related tier (format `lt_...`), or `null`.
type:
type: string
enum:
- UPGRADED
- DOWNGRADED
- JOINED
- LEFT
- PROLONGED
description: >-
Transaction type. `JOINED` — member joined a tier; `LEFT` — member
left a tier; `UPGRADED` — member moved to a higher tier;
`DOWNGRADED` — member moved to a lower tier; `PROLONGED` — the
member's tier membership was prolonged.
details:
$ref: '#/components/schemas/TierTransactionDetails'
status:
type: string
enum:
- PENDING
- APPROVED
- REJECTED
description: >-
Transaction status. `PENDING` — created, awaiting processing;
`APPROVED` — completed successfully; `REJECTED` — rejected (see
`details.rejection`).
created_at:
type: string
format: date-time
description: Timestamp when the transaction was created (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: >-
Timestamp when the transaction was last updated (ISO 8601), or
`null`.
object:
type: string
const: tier_transaction
description: Object type marker. Always `tier_transaction`.
TierTransactionDetails:
type: object
description: >-
Tier transaction details. All fields are nullable; which fields are
populated depends on the transaction type: `JOINED`/`PROLONGED` —
`tier_to`, `start_at`, `expires_at` (no `tier_from`); `LEFT` —
`tier_from` (no `tier_to`); `UPGRADED`/`DOWNGRADED` — both `tier_from`
and `tier_to`.
properties:
points:
type:
- number
- 'null'
description: Points balance relevant to the tier change, or `null`.
tier_from:
type:
- string
- 'null'
description: >-
Unique identifier of the tier the member moved from (format
`lt_...`). `null` for `JOINED` and `PROLONGED` transactions.
tier_to:
type:
- string
- 'null'
description: >-
Unique identifier of the tier the member moved to (format `lt_...`).
`null` for `LEFT` transactions.
origin:
description: What triggered the tier change.
oneOf:
- $ref: '#/components/schemas/TierTransactionOrigin'
- type: 'null'
rejection:
description: >-
Rejection details, present when the transaction was rejected. Known
rejection reason: `SUPERSEDED_BY_LATER_TRANSACTION`.
oneOf:
- $ref: '#/components/schemas/TierTransactionRejection'
- type: 'null'
start_at:
type:
- string
- 'null'
format: date-time
description: Start of the tier membership period, or `null`.
expires_at:
type:
- string
- 'null'
format: date-time
description: Expiration of the tier membership period, or `null`.
TierTransactionOrigin:
type: object
description: Origin of the tier change.
properties:
type:
type: string
enum:
- card_operations
- daily_task_operations
- member_card_created
- member_card_deleted
description: >-
Origin type. `card_operations` — triggered by card point operations;
`daily_task_operations` — triggered by scheduled daily tasks;
`member_card_created` — triggered by creating a member card;
`member_card_deleted` — triggered by deleting a member card.
card_transaction_ids:
type: array
items:
type: string
description: >-
Unique identifiers of the card transactions that triggered the tier
change (format `lctx_...`).
TierTransactionRejection:
type: object
description: Rejection details.
properties:
reason:
type: string
description: >-
Machine-readable rejection reason. Known value:
`SUPERSEDED_BY_LATER_TRANSACTION`.
details:
type: string
description: Additional human-readable details about the rejection.
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
````