> ## 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 card expiring points buckets
>
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.
Returns a cursor-paginated list of points expiration buckets of the member's card.
Each bucket groups active points sharing the same expiration date and expiration
type. Results can be ordered by `expiration_date`. Returns 404 when the program,
member or card does not exist.
## OpenAPI
````yaml /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points
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}/cards/{cardId}/expiring-points:
get:
tags:
- Programs
summary: List card expiring points buckets
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.
Returns a cursor-paginated list of points expiration buckets of the
member's card.
Each bucket groups active points sharing the same expiration date and
expiration
type. Results can be ordered by `expiration_date`. Returns 404 when the
program,
member or card does not exist.
operationId: listCardExpiringPoints
parameters:
- name: programId
in: path
required: true
description: Unique loyalty program ID (format `lprg_[a-f0-9]+`).
schema:
type: string
pattern: ^lprg_[a-f0-9]+$
- name: memberId
in: path
required: true
description: Program member ID (format `lmbr_[a-f0-9]+`).
schema:
type: string
pattern: ^lmbr_[a-f0-9]+$
- name: cardId
in: path
required: true
description: Loyalty card ID (format `lcrd_[a-f0-9]+`).
schema:
type: string
pattern: ^lcrd_[a-f0-9]+$
- name: limit
in: query
required: false
description: >-
Maximum number of buckets to return. Must be between 1 and 100.
Defaults to 10 when not provided.
schema:
type:
- integer
- 'null'
minimum: 1
maximum: 100
default: 10
- name: order
in: query
required: false
description: >-
Field(s) to order results by. Valid orders are `expiration_date` and
`-expiration_date`; defaults to `expiration_date` (soonest
expiration first).
Ordering by the same field in both directions simultaneously is
rejected.
schema:
oneOf:
- type: array
items:
type: string
enum:
- expiration_date
- '-expiration_date'
- type: string
enum:
- expiration_date
- '-expiration_date'
- type: 'null'
- name: cursor
in: query
required: false
description: >-
Pagination cursor returned in the `cursor.next` field of a previous
response.
Must match the pattern `^lcrspeb_[a-f0-9]+$`.
schema:
type:
- string
- 'null'
pattern: ^lcrspeb_[a-f0-9]+$
responses:
'200':
description: Cursor-paginated list of points expiration buckets.
content:
application/json:
schema:
$ref: '#/components/schemas/CardPointsBucketListResponse'
'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:
CardPointsBucketListResponse:
type: object
description: Cursor-paginated list of points expiration buckets.
properties:
data:
type: array
description: Points expiration buckets on the current page.
items:
$ref: '#/components/schemas/CardPointsBucket'
cursor:
description: Pagination cursor, or `null` when there are no more results.
oneOf:
- $ref: '#/components/schemas/ListCursor'
- type: 'null'
object:
type: string
const: list
description: Object type marker, always `list`.
required:
- data
- cursor
- object
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.
CardPointsBucket:
type: object
description: A points expiration bucket of a card.
properties:
id:
type: string
pattern: ^lcpeb_[a-f0-9]+$
description: Unique points expiration bucket ID.
card_id:
type: string
pattern: ^lcrd_[a-f0-9]+$
description: ID of the card the bucket belongs to.
customer_id:
type: string
pattern: ^cust_[a-zA-Z0-9]+
description: ID of the customer owning the card.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: ID of the card definition of the card.
program_id:
type: string
pattern: ^lprg_[a-f0-9]+$
description: ID of the loyalty program.
card_type:
type: string
enum:
- INDIVIDUAL
description: Card type.
member_id:
type: string
pattern: ^lmbr_[a-f0-9]+$
description: ID of the member owning the card.
points:
type: object
description: Points held in the bucket.
properties:
total:
type: number
description: Number of points in the bucket.
required:
- total
expiration_date:
type: string
format: date
description: Date when the points in the bucket expire (`YYYY-MM-DD`).
expiration_type:
type: string
enum:
- NO_EXPIRATION
- ROLLING_EXPIRATION
- CALENDAR_EXPIRATION
- SLIDING_EXPIRATION
description: Points expiration type from the card definition.
status:
type: string
enum:
- ACTIVE
- DELETED
- EXPIRED
description: Bucket status.
created_at:
type: string
format: date-time
description: Timestamp when the bucket was created (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: Timestamp when the bucket was last updated (ISO 8601), or `null`.
object:
type: string
const: card_points_bucket
description: Object type marker, always `card_points_bucket`.
required:
- id
- card_id
- customer_id
- card_definition_id
- program_id
- card_type
- member_id
- points
- expiration_date
- expiration_type
- status
- created_at
- updated_at
- object
ListCursor:
type: object
description: Pagination cursor.
properties:
next:
type: string
description: >-
Cursor value to pass as the `cursor` query parameter to fetch the
next page.
expires_at:
type: string
format: date-time
description: Timestamp when the cursor expires.
required:
- next
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
````