Skip to main content

​
Choose a template

List templates 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 to a blank card. For digital cards, create a digital card 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 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.