Gift cards
Gift cards issues and redeems gift-card codes. Issuance mints a code (shown
once, stored hashed); redemption applies it as (partial) tender at checkout,
decrementing the card’s balance. A card purchased as a product line
(a variant whose SKU begins GIFTCARD) is issued automatically and exactly
once when the order is placed. Redemption at checkout is automatic; issuance,
balance lookup, and void are the routes below.
Every write is idempotent on the Idempotency-Key header, so a retried
issue returns the same card metadata rather than minting a second card.
Gift-card administration (operator-managed)
Tenant-level gift-card administration is operator/console-managed. Merchants issue, list, and void their own cards through the merchant routes below.
| Method | Path | Purpose |
|---|---|---|
POST | /v1/tenants/:tenant/gift-cards | Issue a card — mints a high-entropy code returned here and only here (stored hashed). Idempotency-Key header: a replay returns the same metadata without re-showing the code. Currency is a closed allowlist (USD today) — anything else is a 400 unsupported_currency, never persisted. |
POST | /v1/tenants/:tenant/gift-cards/:id/void | Void a card: zeroes the remaining balance and refuses a double-void with an honest 409. |
GET | /v1/tenants/:tenant/gift-cards/balance | Look up a card’s balance. |
Merchant routes
fdk_ credential, tenant from the credential per credential-carries-ownership,
scope manage:own_giftcards. Mounted at /v1/merchant/gift-cards — the
portal’s gift-cards page.
| Method | Path | Scope | Purpose |
|---|---|---|---|
GET | /v1/merchant/gift-cards | manage:own_giftcards | List the caller’s issued cards. |
POST | /v1/merchant/gift-cards | manage:own_giftcards | Issue a card (fresh idempotency key mints; a replay returns metadata only). Same closed currency allowlist as the operator route. |
POST | /v1/merchant/gift-cards/:id/void | manage:own_giftcards | Void one of the caller’s own cards; a double-void is an honest 409. |
Manifest gates
behavior.giftCards.enabled— purchasable/redeemable gift cards as a checkout tender. Default disabled — a new money surface ships dark. Distinct frombehavior.storeCredit.enabled(the store-credit tender, also default disabled).
Notes
- A lost code cannot be recovered, only re-issued — plaintext is returned once at issuance and never stored (a later read yields the hash only).
- Multi-tender redemption (store credit + gift card + card) is handled at checkout; this API holds the card balance.