Gift Cards

Gift Cards

Overview

Gift cards let customers purchase store credit to give as gifts or to use themselves. They function as a form of payment at checkout — a customer can pay part of an order with a gift card and the remainder with a credit card, and any unused balance stays on the card. All major e-commerce platforms include native gift card functionality; custom implementations are only needed for headless storefronts or very specific accounting requirements.

When to Use This Skill

• When adding gift cards as a purchasable product that customers can send to others
• When implementing store credit as a refund mechanism in place of cash refunds
• When building bulk corporate gift card programs for B2B clients
• When allowing customers to split payment between a gift card and a credit card at checkout
• When you need a full balance history for accounting reconciliation or customer support

Core Instructions

Step 1: Determine the merchant's platform and choose the right tool

Step 2: Set up gift cards on your platform

---

Shopify

Shopify gift cards are available on Shopify, Advanced, and Plus plans (not Basic). They are issued as a product and redeemed at checkout using a 16-character code.

Enable and create gift cards: 1. In your Shopify admin, go to Products → Gift cards 2. Click Add gift card product 3. Set denominations (e.g., $25, $50, $100) — each denomination is a product variant 4. Add a title, description, and image for the gift card product 5. Click Save

Issuing a gift card to a customer:

• Via sale: When a customer purchases a gift card, Shopify automatically generates a unique code and emails it to the recipient
• Manually: Go to Customers → find the customer → Gift cards tab → Issue gift card; set the value and expiry date

Setting expiry dates: 1. In Settings → Gift cards 2. Enable gift card expiry and set the default expiration period 3. Note: Some jurisdictions prohibit gift card expiry (check local law before enabling)

Bulk gift cards for B2B or marketing: 1. Go to Products → Gift cards → Export to download existing codes 2. Use the Shopify Admin API (POST /admin/api/2024-04/gift_cards.json) to bulk-create gift cards programmatically 3. The API response includes the code — distribute via your email platform

Store credit as a refund: When issuing a refund, Shopify allows you to refund to a gift card instead of the original payment method: 1. Go to Orders → open the order → Refund 2. Under "Refund to", select Gift card and specify the amount 3. Shopify creates a new gift card and emails the code to the customer

---

WooCommerce

Install the WooCommerce Gift Cards extension (from WooCommerce.com) or YITH WooCommerce Gift Cards. These are the most feature-complete options.

Setup with WooCommerce Gift Cards: 1. Install and activate the plugin 2. Go to Products → Add New and set the product type to Gift card 3. Under Gift card data:

• Set delivery type: email delivery (for digital) or printed card
• Set available amounts or allow custom amounts
• Configure the email template that sends the code to the recipient

4. Publish the product

Redemption: The plugin adds a "Gift card" field to the checkout page. Customers enter their code and the balance is deducted from the order total. Partial redemption is supported — remaining balance stays on the card.

Store credit as refund: 1. Open the order → Refund 2. The plugin adds a "Refund to gift card" option 3. A new gift card code is generated and emailed to the customer

Balance inquiry: Both WooCommerce Gift Cards and YITH provide a balance inquiry shortcode you can add to a page: [woo_gift_card_balance_check]

---

BigCommerce

BigCommerce calls these "Gift Certificates" and includes them natively.

Create and sell gift certificates: 1. Go to Marketing → Gift Certificates → Create Gift Certificate 2. Fill in:

• To (recipient name and email)
• From (sender name and email)
• Amount: fixed value
• Expiry date (optional)

3. BigCommerce sends the certificate code to the recipient via email

Selling gift certificates as a product: 1. Go to Products → Gift Certificates 2. Enable the gift certificate product page 3. Customers can purchase certificates in custom or fixed amounts directly from your storefront

Redemption: Gift certificate codes appear as a payment option at checkout. Partial redemption is supported — the remaining balance is saved on the certificate code.

---

Custom / Headless

For headless storefronts, implement a ledger-based gift card system. The ledger pattern records every debit and credit as an immutable transaction row — never update a balance column directly.

CREATE TABLE gift_cards (
  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  code         VARCHAR(32) NOT NULL UNIQUE,
  initial_value_cents INTEGER NOT NULL,
  currency     VARCHAR(3) NOT NULL DEFAULT 'USD',
  issued_to    VARCHAR(255),
  expires_at   TIMESTAMPTZ,
  is_active    BOOLEAN NOT NULL DEFAULT true,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE gift_card_ledger (
  id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  card_id    UUID NOT NULL REFERENCES gift_cards(id),
  amount_cents INTEGER NOT NULL,  -- positive = credit, negative = debit
  type       VARCHAR(16) NOT NULL CHECK (type IN ('issue', 'redeem', 'refund', 'void')),
  order_id   UUID,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Balance calculation — always derived from the ledger, never from a stored column:

async function getBalance(cardCode: string): Promise<number> {
  const card = await db.giftCards.findByCode(cardCode.toUpperCase());
  if (!card || !card.is_active) throw new Error('CARD_NOT_FOUND');
  if (card.expires_at && card.expires_at < new Date()) throw new Error('CARD_EXPIRED');

  const result = await db.raw(
    'SELECT COALESCE(SUM(amount_cents), 0) AS balance FROM gift_card_ledger WHERE card_id = ?',
    [card.id]
  );
  return Math.max(0, parseInt(result.rows[0].balance, 10));
}

Partial redemption with row-level locking to prevent concurrent over-redemption:

async function redeemGiftCard(code: string, orderId: string, orderTotalCents: number) {
  return db.transaction(async tx => {
    // Lock the card row to prevent concurrent redemptions
    const card = await tx.raw(
      'SELECT * FROM gift_cards WHERE UPPER(code) = ? FOR UPDATE',
      [code.toUpperCase()]
    ).then(r => r.rows[0]);

    if (!card || !card.is_active) throw new Error('CARD_NOT_FOUND');

    const balance = await getBalance(code);
    const appliedCents = Math.min(balance, orderTotalCents);
    if (appliedCents === 0) throw new Error('ZERO_BALANCE');

    await tx.giftCardLedger.insert({
      card_id: card.id,
      amount_cents: -appliedCents,
      type: 'redeem',
      order_id: orderId,
    });

    return { appliedCents, remainingBalance: balance - appliedCents };
  });
}

Best Practices

• Use an append-only ledger — never update a balance column; record every debit and credit as a transaction row for a full audit trail (required for accounting reconciliation)
• Generate codes without ambiguous characters — omit 0, O, 1, I from the character set to prevent customer confusion when reading codes from email
• Never expose full card codes in URLs or logs — partial masking (ABCD-xxxx-xxxx-MNOP) is safe for display; full codes belong only in the issuance email
• Set accounting liabilities on issuance — gift card balances are a deferred revenue liability until redeemed; ensure your accounting integration records this correctly
• Check local regulations before setting expiry dates — many US states and other jurisdictions restrict or prohibit gift card expiration; verify before enabling
• Test the refund-to-gift-card flow — this is a common customer service scenario; ensure the newly issued card is accessible and redeemable before going live

Common Pitfalls

Related Skills

• @coupon-management
• @loyalty-points-system
• @stripe-integration
• @returns-management
• @checkout-flow-optimization

Gift Card Database Schema for Sprout Home & Garden

Problem Description

Sprout Home & Garden is a mid-sized e-commerce retailer preparing to launch a digital gift card product ahead of the holiday season. The platform is built on PostgreSQL. The engineering team has been tasked with designing the persistence layer for gift cards before the rest of the feature is implemented.

The product requirements are as follows: customers should be able to purchase gift cards for others, cards can be partially used across multiple orders (so a $100 card could be used for a $60 purchase and still have $40 left), and the finance team has strict requirements that every balance change be traceable for accounting reconciliation and customer support inquiries. The customer support team needs to be able to look up the full history of how any given card's balance changed over time. There is also a need to handle card expiration in a way that is reversible and auditable.

Cards will be identified by alphanumeric codes that customers type in during checkout, so lookups must work regardless of whether the customer types the code in upper or lower case.

Output Specification

Write the SQL migration file(s) needed to create the gift card schema in PostgreSQL. Save the output as migration.sql.

Include all tables, constraints, and indexes your design requires. Add brief SQL comments where the purpose of a column or design decision is not self-evident.

Gift Card Checkout Integration for BrightThreads

Problem Description

BrightThreads is a fashion retailer that recently launched gift cards and is now rolling out the checkout integration. The team has run into two production issues they need your help resolving:

Issue 1 — Race condition during flash sales: During a recent flash sale, the same gift card was successfully applied to two different orders at nearly the same time, resulting in the card going negative. The current implementation reads the balance and then inserts the redemption transaction as two separate steps with no locking, allowing concurrent requests to both see the old balance before either debit is recorded.

Issue 2 — Missing balance after refunds: Several customers who received refunds back to their gift cards reported that their cards appeared to have zero balance in the UI even though a refund was issued. Investigation showed that when a card reaches zero balance the system marks it in a way that causes subsequent lookups to short-circuit and skip the balance calculation.

Your task is to implement the corrected redeemGiftCard and refundToGiftCard TypeScript functions. Customers should be able to apply a gift card even when it doesn't cover the full order total (the remainder should be charged to their other payment method), and refunds should always restore the correct spendable balance.

Assume the following are available as imports:

• db — a database client with .transaction(), .raw(sql, params), .giftCards.findByCode(), .giftCards.update(), and .giftCardTransactions.insert() methods
• The getGiftCardBalance(code) helper is already implemented and returns { card, balanceCents }

Output Specification

Write a TypeScript file named giftCardCheckout.ts containing: 1. The redeemGiftCard(code, orderId, orderTotalCents) function — returns { appliedCents, remainingBalance, remainingOrderTotal } 2. The refundToGiftCard(code, orderId, refundCents) function — returns void

Include any necessary TypeScript interfaces. The file should compile without errors assuming the db and getGiftCardBalance imports exist.

Gift Card Issuance Service for PetStuff Online

Problem Description

PetStuff Online is a direct-to-consumer pet supply store that has just approved a gift card feature for Q4. When a customer purchases a gift card, the platform needs to: generate a unique code for the card, persist it to the database, and automatically send the recipient an email so they can use it.

The engineering lead has flagged a concern from a past incident at another company: gift card codes ended up in server access logs because they were passed as URL path parameters, exposing customer credit to anyone with log access. The new implementation should be designed with this in mind. The team also wants codes to be practical for customers to use — cards may be printed, shown on screens, or read aloud during customer support calls.

The store's database already has a gift_cards table and a gift_card_transactions ledger table (similar to a double-entry bookkeeping approach). Your task is to implement the TypeScript service function that handles card issuance end-to-end: generating the code, writing to the database, and dispatching the notification email.

Assume the following are available as imports:

• db — a database client with .transaction(), .giftCards.insert(), and .giftCardTransactions.insert() methods
• emailService — an email client with .send({ to, template, data }) method
• crypto from Node.js standard library

Output Specification

Write a TypeScript file named issueGiftCard.ts containing: 1. The generateGiftCardCode() function 2. The issueGiftCard(params) function that creates the card, records the ledger entry, and sends the email

The file should be self-contained and runnable. Include the type definitions for any interfaces used.