--- title: "Get loyalty card" method: GET path: "/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}" tags: ["Loyalty cards"] --- # Get loyalty card `GET /v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}` ## Request - Base URL: `https://yourbaseurl.talon.one` - URL: `https://yourbaseurl.talon.one/v1/loyalty_programs/{loyaltyProgramId}/cards/{loyaltyCardId}` - Auth: one of: - API key in header `Authorization` - API key in header `Authorization` - TypeScript: (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. Get the given loyalty card. ## Path parameters - `loyaltyProgramId` integer, required - `loyaltyCardId` string, required ## Response `200` OK - LoyaltyCard - `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 - `404`: Not found ## Changes - **2026-11-07** `7ef1b9504c3a`: 5 info - added the optional property `allOf[#/components/schemas/UpdateLoyaltyCard]/attributes` to the response with the `200` status - added the optional property `allOf[subschema #4]/ledger/allOf[subschema #2]/currentTier/reason` to the response with the `200` status - added the optional property `allOf[subschema #4]/ledger/allOf[subschema #2]/currentTier/source` to the response with the `200` status - added the optional property `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/:loyaltyCardId/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)