---
title: "List loyalty cards"
method: GET
path: "/v1/loyalty_programs/{loyaltyProgramId}/cards"
tags: ["Loyalty cards"]
---

# List loyalty cards

`GET /v1/loyalty_programs/{loyaltyProgramId}/cards`

## Request

- Base URL: `https://yourbaseurl.talon.one`
- URL: `https://yourbaseurl.talon.one/v1/loyalty_programs/{loyaltyProgramId}/cards`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/talon/apis/management-api/docs/v1/loyalty_programs/:loyaltyProgramId/cards/get.ts> (a function with typed inputs; its response is checked against the schema)

> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

For the given card-based loyalty program, list the loyalty cards that match your filter criteria.

## Path parameters

- `loyaltyProgramId` integer, required

## Query parameters

- `pageSize` integer
- `skip` integer
- `sort` string
- `identifier` string
- `profileId` integer
- `batchId` string

## Response `200`

OK

- object
  - `hasMore` boolean, required
  - `data` LoyaltyCard[], required
    - `id` integer, required: The internal ID of this entity.
    - `created` string, date-time, required: The time this entity was created.
    - `programID` integer, required: The ID of the loyalty program that owns this entity.
    - `programName` string: The integration name of the loyalty program that owns this entity.
    - `programTitle` string: The Campaign Manager-displayed name of the loyalty program that owns this entity.
    - `status` string, required: Status of the loyalty card. Can be `active` or `inactive`.
    - `blockReason` string: Reason for transferring and blocking the loyalty card.
    - `attributes` object: Set values for the [custom attributes](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes) of a loyalty card. These attributes must be created in the Campaign Manager before their values can be updated through this endpoint.
    - `identifier` string, required: The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`.
    - `usersPerCardLimit` integer, required: The max amount of customer profiles that can be linked to the card. 0 means unlimited.
    - `profiles` LoyaltyCardProfileRegistration[]: Integration IDs of the customers profiles linked to the card.
      - `integrationId` string, required: Integration ID of the customer profile linked to the card.
      - `timestamp` string, date-time, required: Timestamp the customer profile was linked to the card.
    - `ledger` LedgerInfo: The balance in a Loyalty Program for some Customer.
      - `currentBalance` number, required: Sum of currently active points.
      - `pendingBalance` number, required: Sum of pending points.
      - `negativeBalance` number: Sum of negative points. This implies that `currentBalance` is `0`.
      - `expiredBalance` number, required: **DEPRECATED** Value is shown as 0.
      - `spentBalance` number, required: **DEPRECATED** Value is shown as 0.
      - `tentativeCurrentBalance` number, required: The tentative points balance, reflecting the `currentBalance` and all point additions and deductions within the current open customer session. When the session is closed, the effects are applied and the `currentBalance` is updated to this value. **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer.
      - `tentativePendingBalance` number: The tentative points balance, reflecting the `pendingBalance` and all point additions with a future activation date within the current open customer session. When the session is closed, the effects are applied and the `pendingBalance` is updated to this value. **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer.
      - `tentativeNegativeBalance` number: The tentative negative balance after all additions and deductions from the current customer session are applied to `negativeBalance`. When the session is closed, the tentative effects are applied and `negativeBalance` is updated to this value. **Note:** Tentative balances are specific to the current session and do not take into account other open sessions for the given customer.
      - `currentTier` Tier
        - `id` integer, required: The internal ID of the tier.
        - `name` string, required: The name of the tier.
        - `startDate` string, date-time: Date and time when the customer moved to this tier. This value uses the loyalty program's time zone setting.
        - `expiryDate` string, date-time: Date when tier level expires in the RFC3339 format (in the Loyalty Program's timezone).
        - `downgradePolicy` 'one_down' | 'balance_based': The policy that defines how customer tiers are downgraded in the loyalty program after tier reevaluation. - `one_down`: If the customer doesn't have enough points to stay in the current tier, they are downgraded by one tier. - `balance_based`: The customer's tier is reevaluated based on the amount of active points they have at the moment.
        - `source` 'boost' | 'points': Indicates whether the customer's current tier was determined based on their points balance or a temporary boost. - `points`: The tier reflects the customer's current point balance. - `boost`: A temporary tier boost is in effect where the customer is in a higher tier than their points-based tier. The boost expires after a set duration and the customer returns to their points-based tier.
        - `reason` string: The reason for the tier assignment.
      - `pointsToNextTier` number: Points required to move up a tier.
      - `nextTierName` string: The name of the next higher tier level in the loyalty program. **Note**: - Returns `null` if the customer has reached the highest available tier. - Returns the lowest level tier name if the customer is not currently assigned to any tier.
    - `subledgers` object: Displays point balances of the card in the subledgers of the loyalty program.
    - `modified` string, date-time: Timestamp of the most recent update of the loyalty card.
    - `oldCardIdentifier` string: The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`.
    - `newCardIdentifier` string: The identifier of the loyalty card, which must match the regular expression `^[A-Za-z0-9._%+@-]+$`.
    - `batchId` string: The ID of the batch in which the loyalty card was created.

## Other responses

- `400`: Bad request
- `401`: Unauthorized

## Changes

- **2026-11-07** `7ef1b9504c3a`: 5 info
  - added the optional property `data/items/allOf[#/components/schemas/UpdateLoyaltyCard]/attributes` to the response with the `200` status
  - added the optional property `data/items/allOf[subschema #4]/ledger/allOf[subschema #2]/currentTier/reason` to the response with the `200` status
  - added the optional property `data/items/allOf[subschema #4]/ledger/allOf[subschema #2]/currentTier/source` to the response with the `200` status
  - added the optional property `data/items/allOf[subschema #4]/subledgers/additionalProperties/allOf[subschema #2]/currentTier/reason` to the response with the `200` status
  - …1 more

[Operation history](https://skmtc.dev/talon/apis/management-api/changes/v1/loyalty_programs/:loyaltyProgramId/cards/get.md)

---

[API](https://skmtc.dev/talon/apis/management-api.md) - [All operations](https://skmtc.dev/talon/apis/management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talon/apis/management-api/revisions/7ef1b9504c3a?raw)