Gift cards

The gift card module issues and manages serial-numbered store credit. Each card has a serial, a balance, an owner (or no owner if unassigned), and a transaction history. Cards are first-class payment instruments at checkout — applied like a discount but tracked as redemption against a balance.

Public balance check

The only gift-card endpoint without auth. Pass serial and pin as query params; returns the balance and currency. Customer-facing "check your balance" pages call this directly.

curl "https://appengine.appmint.io/storefront/giftcards/balance?serial=GC-ABCD-1234&pin=4892" \
  -H "orgid: my-org"

{ "serial": "GC-ABCD-1234", "balance": 75.00, "currency": "USD", "status": "active" }

Redemption

Applies a card against a cart at checkout. Body carries serial, pin, and the cart context. The response includes the amount applied (lesser of card balance and cart total) and the resulting card balance.

const redemption = await fetch('/api/storefront/giftcards/redeem', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', orgid: ORG_ID },
  body: JSON.stringify({
    serial: 'GC-ABCD-1234',
    pin: '4892',
    cartId: cartId,
    amount: 50.00,
  }),
}).then(r => r.json());

If amount is omitted, the platform applies the maximum the card can cover.

Issuance (staff)

Single or batch issuance. Single body:

{
  "amount": 100,
  "currency": "USD",
  "ownerEmail": "[email protected]",
  "expiresAt": "2027-04-25",
  "deliverEmail": true,
  "design": "holiday-2026"
}

Setting deliverEmail: true sends a branded email with the serial, PIN, and a redemption link. Batch accepts an array — used for bulk issuance to employees, contest winners, or partner programmes.

Listing and details

Stats returns issued count, total face value, redeemed amount, outstanding liability — the numbers your finance team needs for the balance sheet.

Lifecycle

A card is active, suspended, or cancelled. Only active cards redeem. Suspended cards can be reactivated; cancelled cards can't.

Refund

Refunds an amount back onto the card balance. Used when an order paid with a gift card is returned — the cash side goes to the original payment method, the gift-card side goes back on the card.

Transfer ownership

Reassign a card to a different owner email. Useful for support flows ("I bought this for my partner; reassign to their account").

Transactions

Every redemption and refund writes a transaction record on the card. Read them via the data layer:

curl "/api/data/giftcard-transaction?where[giftCardSerial]=GC-ABCD-1234" \
  -H "orgid: my-org" -H "Authorization: Bearer ${jwt}"

The audit trail is immutable — there's no delete on transactions.

At checkout

The cart accepts up to N gift cards alongside one card-on-file payment. The order workflow:

1. Customer enters serial and PIN. UI calls redeem with the cart.
2. Cart total reduces by the redemption amount.
3. If a balance remains, the customer pays it with another method (Stripe, PayPal).
4. On order completion, the redemption is committed and the card balance is locked at the new amount.
5. On order cancellation before fulfillment, the redemption reverses automatically.