---
title: "List card expiring points buckets"
method: GET
path: "/v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points"
tags: ["Programs"]
---

# List card expiring points buckets

`GET /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points`

## Request

- Base URL: `https://api.voucherify.io`
- URL: `https://api.voucherify.io/v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points`
- Auth: one of:
  - API key in header `X-App-Id` and API key in header `X-App-Token`
  - HTTP bearer

Returns a cursor-paginated list of `ACTIVE` point expiration buckets for the member's card. Each bucket groups points that share an expiration date and expiration type, including points from separate transactions.

The list starts on the current project day. Earlier buckets are omitted.

Results can be filtered by card definition ID and expiration date, and ordered by `expiration_date`.

Returns an empty list when the card has no matching buckets. Returns `400` when the query is invalid or the cursor is invalid, expired, or doesn't match the query. Returns `404` when the program or the member doesn't exist, or when the card isn't assigned to that member.

## Query parameters

- `limit` integer, nullable
- `order` union
  - string[]
  - 'expiration_date' | '-expiration_date'
- `cursor` string, nullable
- `filters` V2LoyaltiesProgramsMembersCardsExpiringPointsListRequestQuery: Request query schema for **GET** `/v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points`.
  - `junction` 'AND' | 'OR', nullable: Joins the field filters. Allowed values are `AND` and `OR`. Defaults to `AND`.
  - `card_definition_id` CardDefinitionIdFilterConditions: ID conditions. Format `lcdef_[a-f0-9]+`. At least one condition is required.
    - `conditions` object, required
      - `$is` union: Matches one value. A string or a one-element array. Format `lcdef_[a-f0-9]+`.
        - string
        - string[]
      - `$is_not` union: Excludes one value. A string or a one-element array. Format `lcdef_[a-f0-9]+`.
        - string
        - string[]
      - `$in` union: Matches any of the values. A string or an array of 1 to 100 values. Format `lcdef_[a-f0-9]+`.
        - string
        - string[]
      - `$not_in` union: Excludes any of the values. A string or an array of 1 to 100 values. Format `lcdef_[a-f0-9]+`.
        - string
        - string[]
  - `expiration_date` DateFilter: Date filter conditions. `$before`/`$after` take date strings (ISO 8601); `$is`, `$more_than`, `$less_than` take non-negative integers; `$has_value`/`$is_unknown` are presence checks. Each condition accepts a single value or an array with exactly one value. At least one condition is required.
    - `conditions` object, required
      - `$before` union: Matches dates before the given value. An ISO 8601 date-time, as a string or a one-element array.
        - string, date-time
        - string[]
      - `$after` union: Matches dates after the given value. An ISO 8601 date-time, as a string or a one-element array.
        - string, date-time
        - string[]
      - `$is` union: Matches a date exactly the given number of days ago. A non-negative integer, as a string or a one-element array.
        - string
        - string[]
      - `$more_than` union: Matches dates more than the given number of days ago. A non-negative integer, as a string or a one-element array.
        - string
        - string[]
      - `$less_than` union: Matches dates less than the given number of days ago. A non-negative integer, as a string or a one-element array.
        - string
        - string[]
      - `$has_value` string, nullable: Matches when the field is set. The condition value is ignored.
      - `$is_unknown` string, nullable: Matches when the field is not set. The condition value is ignored.

## Response `200`

Cursor-paginated list of points expiration buckets.

- V2LoyaltiesProgramsMembersCardsExpiringPointsListResponseBody: Cursor-paginated list of points expiration buckets.
  - `data` CardPointsBucket[], required: Points expiration buckets on the current page.
    - `card_id` string, required: ID of the card the bucket belongs to.
    - `card_definition_id` string, required: ID of the card definition of the card.
    - `program_id` string, required: ID of the loyalty program.
    - `member_id` string, required: ID of the member owning the card.
    - `card_type` 'INDIVIDUAL', required: Card type. Currently, only `INDIVIDUAL` is supported.
    - `created_at` string, date-time, required: Timestamp when the bucket was created (ISO 8601).
    - `updated_at` string, date-time, nullable, required: Timestamp when the bucket was last updated (ISO 8601), or `null`.
    - `id` string, required: Unique points expiration bucket ID.
    - `customer_id` string, required: Voucherify ID of the customer owning the card.
    - `points` object, required: Points held in the bucket. The bucket may include points from multiple transactions.
      - `total` number, required: Number of points in the bucket.
    - `expiration_date` string, date, required: Date when the points in the bucket expire (`YYYY-MM-DD`).
    - `expiration_type` 'NO_EXPIRATION' | 'ROLLING_EXPIRATION' | 'CALENDAR_EXPIRATION' | 'SLIDING_EXPIRATION', required: Points expiration type for the bucket. It can be inherited from the card definition or overridden by the earning rule.
    - `status` 'ACTIVE' | 'DELETED' | 'EXPIRED', required: Bucket status. For the List card expiring points buckets, returns only `ACTIVE` buckets.
    - `object` 'card_points_bucket', required: Object type marker, always `card_points_bucket`.
  - `cursor` ListCursor, required: Pagination cursor.
    - `next` string, required: Cursor value to pass as the `cursor` query parameter to fetch the next page.
    - `expires_at` string, date-time, required: Timestamp when the cursor expires.
  - `object` 'list', required: Object type marker, always `list`.

## Other responses

- `400`: Invalid query parameters or pagination cursor.
- `404`: Resource (program, member, card) not found.
- `500`: Internal server error.

## Changes

- **2026-10-15** (v2) `4134cde57cda`: 1 breaking, 1 info
  - removed the required property `allOf[#/components/schemas/CardExpiringPointsListResponse]/data/items/allOf[subschema #2]/card_type` from the response with the `200` status
  - added the required property `allOf[#/components/schemas/CardExpiringPointsListResponse]/data/items/allOf[#/components/schemas/CardBucketBase]/card_type` to the response with the `200` status
- **2026-10-14** (v2) `0d886da710c9`: 1 breaking, 1 info
  - removed the required property `allOf[#/components/schemas/CardExpiringPointsListResponse]/data/items/allOf[#/components/schemas/CardBucketBase]/card_type` from the response with the `200` status
  - added the required property `allOf[#/components/schemas/CardExpiringPointsListResponse]/data/items/allOf[subschema #2]/card_type` to the response with the `200` status
- **2026-10-14** (v2) `f53d017a25d6`: 1 breaking, 1 info
  - removed the required property `allOf[#/components/schemas/CardExpiringPointsListResponse]/data/items/allOf[subschema #2]/card_type` from the response with the `200` status
  - added the required property `allOf[#/components/schemas/CardExpiringPointsListResponse]/data/items/allOf[#/components/schemas/CardBucketBase]/card_type` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/changes/v2/loyalties/programs/:programId/members/:memberId/cards/:cardId/expiring-points/get.md)

---

[API](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-loyalty-v2-api/revisions/e0d9f2d2532f?raw)