Gift Cards Architecture & Technical Specs

A gift card purchase starts in a pending state until payment is confirmed, then transitions to active.

What happens on purchase:

1. One or more cards are generated for the requested quantity, each with its own code, PIN, and expiration date.
2. A purchase transaction is logged against each card with a unique idempotency key, so a retried request never creates duplicate cards or duplicate charges.
3. If a promotional template was used, its usage count and total value generated are updated for analytics.
4. The response returns the new card(s) with a pending_payment status.

Activation (after payment):

1. Once payment is confirmed, the card transitions from pending to active and an activation timestamp is recorded.
2. An activation transaction is logged for the audit trail.
3. If the card has an email delivery method and a recipient, a delivery event fires — this is what triggers the recipient's email (immediately or on a scheduled date).

See the Getting Started guide for exact request/response shapes.

Redemption calculates exactly how much to deduct from the gift card and how much remains for the primary payment method — as a true partial payment, not a discount that silently changes the order total.

How it works:

`

Order total: $100, Gift card balance: $30 → chargedAmount: $30 (max available on card) → remainingOrderAmount: $70 (passed to your payment gateway) → isPartial: true (gift card couldn't cover the full order)

If the card had $100 and the order was $80: → chargedAmount: $80 (full order covered by card) → remainingOrderAmount: $0 (no split payment needed) → isPartial: false

`

Every redemption carries a unique idempotency key built from the order and card, so a retried request (a flaky connection at checkout, a double-tap on submit) never double-charges a card.

Balance checks validate the code, PIN, card status, and available balance before returning how much of a given amount the card can cover.

Reloading a card's balance is an atomic operation — if two reload requests land at the same time (a double-click, a retried request), exactly one succeeds and the other is safely rejected as a conflict rather than corrupting the balance.

What's enforced automatically:

• Reloads are blocked on canceled, expired, or non-reloadable cards
• A configurable maximum balance cap prevents overfunding a card
• Every reload is logged as its own transaction with a before/after balance snapshot
• A confirmed final balance is always returned, even under concurrent load

If a conflict is detected, the API returns a clear conflict response so the client can safely retry.

Gift cards can be transferred to another recipient — useful for re-gifting or correcting a delivery mistake.

What happens on transfer:

1. The previous owner's code and PIN are immediately invalidated.
2. A new code and PIN are generated for the recipient.
3. The transaction is logged with both sender and recipient details for a full audit trail.
4. A notification fires so the new recipient can be delivered their card by email.

Store credit is modeled as its own wallet type, distinct from purchased gift cards, so finance teams can separate real financial liability (purchased cards) from goodwill or return credit in reporting.

How issuance works:

• If the customer already has an active store-credit wallet in that currency, the new credit is added to it atomically.
• If not, a new wallet is created automatically with its own unique code.
• Every issuance is logged as its own transaction, tagged with a reason (e.g., "Return — item not as described") and linked to the originating order.

This distinction — store credit vs. purchased gift card — is what powers accurate liability vs. breakage reporting for finance teams.