> ## Documentation Index
> Fetch the complete documentation index at: https://tapcoupon.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Card lifecycle

> Issue cards, handle renewals, and reconfigure eligible card instances.

## Choose a template

[List templates](https://tapcoupon.mintlify.site/api-reference/templates/list.md) and offer active templates for the desired card type. Points and status templates reference programs managed in the dashboard. `isLocationBound` restricts the card to the issuing location. `lifetime` is in hours from the card's creation time; `0` disables lifetime expiry.

Fixed coupon templates have `isAmountSpecified: true` and use the template amount. Variable coupon templates require a positive `amount` in cents in the issuance request.

## Issue a card

For physical cards, [apply a template](https://tapcoupon.mintlify.site/api-reference/cards/apply-template.md) to a blank card. For digital cards, [create a digital card](https://tapcoupon.mintlify.site/api-reference/cards/create-digital.md) and supply the customer's email and nested contact information. The customer receives a QR code by email.

Both routes require an API key, stable device id, and employee token. Real digital issuance requires an active subscription. Send `testCard: true` for test issuance during the account's test window, subject to its card limit. Read [client configuration](https://tapcoupon.mintlify.site/api-reference/other/client-config.md) for current availability. Test cards cannot be used after the test period ends.

## Use a card

A card must be active, unarchived, unexpired, and eligible for the current location. Coupon deductions use cents. Points and status awards use points. Loyalty scans add one stamp and return `rewardEarned`.

A loyalty card with renewals left immediately starts another cycle after a reward. The response can show a reset stamp count; use `rewardEarned`, not `scansLeft`, to trigger reward fulfillment. A final reward without another renewal succeeds; later scans return `422`.

Status programs use a rolling window of `program.durationDays`. Older awards expire even when the card is only read. The tier and points can decrease without another scan. Points cards have a spendable balance and per-reward cooldowns.

## Reconfigure a physical card

Use `POST /cards/apply` again when a card is fully used. The printed `cardId` remains the same while the prior instance is archived and a new instance is created. Use the database `id` to distinguish history entries.

You can cancel and replace a fresh, unused card with `cancelPrevious: true`. Cancellation is rejected for blank cards, used cards, and cards already billed. An unfinished card cannot be overwritten through normal reconfiguration.

There is no POS `POST /card/{cardId}/reset` route. Follow the eligibility rules on [apply template](https://tapcoupon.mintlify.site/api-reference/cards/apply-template.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.