What a code looks like
Sixteen hexadecimal characters in groups of four:a1b2c3d4e5f67890 works just as well.
Two ways to get the credits
- Enter a code
- Batch claim link
Go to
/redeem and enter the code. The system previews it first (face value, status, expiry, who bought it), then redeems on confirmation.1
Open the redemption page
The “Redeem gift card” entry on the billing page, or go straight to
/redeem.2
Enter the code and preview
You see the card’s face value, current status, and expiry date — enough to confirm it is the card you meant.
3
Confirm
Credits land immediately and a
GIFT_CARD_REDEEM entry appears in your credit ledger.Code state machine
The difference between frozen and voided is reversibility: frozen means “on hold, may be released”, voided means “this card no longer exists”. A redeemed card cannot be voided — the credits are already out, and voiding would only break the books.
Validity
Note where the clock starts: the card starts aging the moment payment succeeds. A card that sat around for 80 days before being handed over leaves the recipient 10 days.
Because the sweep runs every 5 minutes, a just-expired card may briefly still show as
unused — but redemption re-checks the time and marks it expired on the spot, so it never actually redeems.
Per-user claim limit
A batch can cap how many cards one user may take, defaulting to 1. The cap is frozen at batch creation and cannot be changed afterwards. The check is serialized with a PostgreSQL advisory lock keyed on(batchNo, userId), which is worth explaining: under Read Committed, two concurrent requests would both read “0 claimed” and both proceed. The lock is what makes the count a count of committed state. So double-clicking the claim button does not get you two cards.
Code redemption and batch claiming share the same lock and the same counter, so there is no “claim one from the link, then type in another code” bypass.
Buying
A fourth pending order is rejected with
GIFT_CARD_TOO_MANY_PENDING — pay off an old one or let it expire.
Buying N cards generates N independent codes under one batch number. Under “My gift cards”, batches of 5 or more are shown aggregated and smaller ones are expanded into individual cards. That threshold lives server-side so that buying 1,000 cards does not push a thousand rows to the browser.
Admin-issued batches are capped at 1,000 cards per batch by default (adjustable in operations configuration).
Failures and what to do
Redemption is idempotent: if the same card’s redemption request arrives twice, the system recognizes from the ledger’s business key that this card already credited this user and returns success without crediting again.
How the credits behave
Gift card credits are recorded as BONUS with business typeGIFT_CARD_REDEEM. Once in, they are indistinguishable from other bonus credits and follow the same consumption priority and expiry rules.
For team users: gift card credits always land in your personal credit account. They do not enter the team credit pool and are unaffected by your current billing-subject setting. To fund a team, top up the team pool — do not use gift cards.
FAQ
Can gift cards be refunded?
Can gift cards be refunded?
No — there is no gift card refund path in the code. An unredeemed code can be given to someone else, and that is the only way to undo a purchase.
When does the validity period start?
When does the validity period start?
At generation — the moment payment succeeded for a purchased card, or the moment an admin issued a gift batch. Not when you received or claimed it.
Can a batch link be forwarded?
Can a batch link be forwarded?
Yes; the link carries no identity. But every claimer must sign in and the per-user cap applies, so forwarding it to a group chat makes it first come, first served.
Can I see who sent a card?
Can I see who sent a card?
Yes. Both the redemption preview and the batch claim page show the buyer’s name.
Where do I find the record afterwards?
Where do I find the record afterwards?
The billing page’s credit ledger has a
GIFT_CARD_REDEEM entry with the timestamp and amount, and the “Redemption records” list shows every card you have redeemed.Keep reading
Credits
Consumption priority and expiry across all six credit buckets
Top-up
Direct top-ups and bonus ratios
Error codes
Every
GIFT_CARD_* codeTeam billing
Where the team pool ends and the personal account begins