Gift Card Management

The Gift Card system provides a complete solution for selling and managing gift cards as flexible payment options. Customers can purchase gift cards for themselves or as gifts, and redeem them during checkout.

Gift Card Overview

Gift cards function as stored value payment instruments:

Unique Codes: Each gift card has a unique redemption code
Balance Tracking: Monitor remaining value after transactions
Expiration Dates: Set optional expiration periods
Regional Restrictions: Limit usage to specific regions
Transaction History: Track all usage and balance changes
Disabled State: Temporarily or permanently disable cards

Gift Card List

The gift card list displays all created cards:

Code: Unique redemption code (partially masked for security)
Value: Original gift card amount
Balance: Remaining redeemable value
Status: Active or inactive/disabled
Region: Where the card can be used
Order: Original purchase order (if applicable)
Expiration: Expiration date if set
Created: When the card was created

Status Filtering

Active

Gift cards that can be used for purchases

Inactive

Disabled, expired, or fully redeemed gift cards

All

Complete list of all gift cards regardless of status

Creating Gift Cards

Click Create Gift Card

Open the gift card creation form from the list page.

Set Gift Card Value

Enter the monetary value for the gift card.

Choose Region

Select which region and currency the card uses.

Generate or Enter Code

Use auto-generated code or create a custom one.

Set Expiration (Optional)

Add an expiration date if desired.

Link to Order (Optional)

Associate with a purchase order if sold to customer.

Create Gift Card

Save the gift card and optionally send to recipient.

Gift Card Properties

Code: Unique identifier for redemption

// Auto-generated format
"GC-XXXX-XXXX-XXXX-XXXX"

// Custom codes also supported
"SUMMER2024" or "WELCOME100"

Value: Original gift card amount in region’s currency

{
  value: 10000,        // $100.00 in cents
  balance: 10000,      // Full balance available
  currency: "USD",
  region: "United States"
}

Expiration: Optional expiration date

{
  endsAt: "2024-12-31T23:59:59Z",
  daysUntilExpiration: 45,
  isExpired: false
}

Gift Card Details

Basic Information

Card Status:

Active: Can be used for purchases
Disabled: Manually disabled by admin
Expired: Past expiration date
Depleted: Balance is zero

Financial Details:

Original value
Current balance
Total used amount
Currency and region

Lifecycle Information:

Creation date
Last used date
Expiration date (if set)
Associated order

Purchase Information

When gift cards are purchased by customers: Original Order:

Order number and date
Customer who purchased
Purchase price paid
Delivery email
Gift message (if provided)

Recipient Details:

{
  recipientName: "Jane Smith",
  recipientEmail: "[email protected]",
  senderName: "John Doe",
  giftMessage: "Happy Birthday!",
  deliveryDate: "2024-03-15"
}

Transaction History

Track all gift card usage:

Transaction Details

Each transaction record includes: Order Information:

Order number
Order date
Order total
Customer name

Transaction Amount:

{
  amount: 2500,           // $25.00 used
  balanceBefore: 10000,   // $100.00
  balanceAfter: 7500,     // $75.00 remaining
  transactionDate: "2024-02-15T10:30:00Z"
}

Transaction Types:

Purchase: Gift card applied to order
Refund: Amount returned to gift card
Adjustment: Manual balance change
Void: Transaction canceled

Balance Changes

Monitor balance over time:

[
  {
    date: "2024-01-01",
    type: "created",
    amount: 10000,
    balance: 10000,
    note: "Gift card created"
  },
  {
    date: "2024-01-15",
    type: "purchase",
    amount: -2500,
    balance: 7500,
    order: "#1234"
  },
  {
    date: "2024-01-20",
    type: "purchase",
    amount: -3000,
    balance: 4500,
    order: "#1289"
  }
]

Gift Card Redemption

Customer Redemption Flow

How customers use gift cards:

Add to Cart

Customer adds products to shopping cart.

Proceed to Checkout

Begin checkout process.

Enter Gift Card Code

Input gift card code in payment section.

Verify Card

System validates code, balance, region, and expiration.

Apply to Order

Gift card amount applied to order total.

Complete Order

Pay any remaining balance with other payment method.

Validation Rules

Gift cards must pass these checks:

Code Validity

Code exists in system
Code format is correct
No typos or invalid characters

Status Check

Card is not disabled
Card has not expired
Card has available balance

Regional Compatibility

Card region matches order region
Currency matches order currency
Card available in customer’s location

Balance Requirements

Balance is greater than zero
Card can be partially redeemed
Remaining balance carried forward

Partial Redemption

Gift cards can be used across multiple orders: Example Scenario:

// $100 gift card
initialBalance: 10000

// First order: $35
order1Amount: 3500
remainingBalance: 6500

// Second order: $42
order2Amount: 4200
remainingBalance: 2300

// Third order: $80 (exceeds balance)
giftCardApplied: 2300
additionalPaymentRequired: 5700
remainingBalance: 0

Managing Gift Cards

Disabling Gift Cards

Temporarily or permanently disable cards:

Open Gift Card

Navigate to the specific gift card.

Toggle Disabled Status

Set isDisabled to true.

Add Note

Document reason for disabling.

Save Changes

Card can no longer be used until re-enabled.

Common Reasons to Disable:

Suspected fraud or unauthorized use
Lost or stolen card
Customer request
Promotional period ended
Terms violation

Adjusting Balances

Manually modify gift card balances:

Balance adjustments should be documented and require appropriate permissions. All adjustments are tracked in transaction history.

Adjustment Scenarios:

Compensate for system error
Add promotional bonus
Correct incorrect redemption
Refund to gift card
Customer service resolution

Extending Expiration

Change expiration dates:

// Original expiration
endsAt: "2024-06-30T23:59:59Z"

// Extended by 90 days
endsAt: "2024-09-28T23:59:59Z"
reason: "Customer service extension"

Gift Card Products

Creating Gift Card Products

Sell gift cards as products in your store:

Create Product

Create a new product in the product catalog.

Mark as Gift Card

Toggle the “isGiftcard” property to true.

Create Variants

Add variants for different denominations (

25,

50, $100, etc.).

Set Pricing

Price variants at their face value.

Configure Options

Add options for delivery method (email, physical).

Publish Product

Make gift cards available for purchase.

Common Denominations:

$25
$50
$75
$100
$150
$200
Custom amount (if supported)

Gift Card Fulfillment

Email Delivery:

Instant delivery after purchase
Includes gift card code
Optional gift message
Scheduled delivery option
Printable certificate

Physical Delivery:

Physical gift card mailed
Code activated upon shipping
Greeting card included
Gift wrapping options
Expedited shipping available

Reporting & Analytics

Gift Card Metrics

Track gift card performance: Sales Metrics:

{
  totalSold: 456,
  totalValue: 45600.00,
  averageValue: 100.00,
  salesByMonth: [...],
  popularDenominations: [50, 100, 25]
}

Redemption Metrics:

{
  redemptionRate: 78.5,      // Percentage used
  averageDaysToRedeem: 45,
  totalRedeemed: 35780.00,
  partialRedemptions: 234,
  fullRedemptions: 178
}

Outstanding Liability:

{
  activeCards: 278,
  totalOutstandingBalance: 9820.00,
  averageBalance: 35.32,
  expiringIn30Days: 12,
  expiringValue: 580.00
}

Export Options

Gift Card List

Export all gift cards with codes, values, and balances

Transaction Report

Detailed transaction history for accounting

Redemption Report

Usage patterns and redemption analytics

Liability Report

Outstanding balance for financial reporting

Best Practices

Code Security

Use complex, unique codes
Mask codes in customer communications
Implement rate limiting on verification
Monitor for fraud patterns
Disable suspicious cards immediately

Expiration Policies

Clearly communicate expiration terms
Send reminder emails before expiration
Consider extending high-value cards
Comply with regional gift card laws
Allow reasonable expiration periods

Customer Service

Provide easy balance check method
Respond quickly to issues
Replace lost/stolen cards when appropriate
Make redemption process simple
Clearly explain terms and conditions

Financial Management

Track gift card liability accurately
Reconcile regularly
Plan for breakage revenue
Follow accounting standards
Report outstanding balances

Troubleshooting

Gift card not applying at checkout

Verify code is entered correctly
Check card is active and not expired
Confirm region matches order
Ensure balance is available
Verify currency compatibility

Balance discrepancy

Review transaction history
Check for duplicate redemptions
Verify refund processing
Reconcile with order records
Contact support if unresolved

Customer can’t find gift card email

Check spam/junk folders
Verify email address is correct
Resend gift card notification
Provide code via alternative method
Check email delivery logs

Physical gift card not received

Track shipping status
Verify shipping address
Check estimated delivery date
Reship if lost in transit
Activate replacement card

Getting Started

Core Concepts

Admin Dashboard

Storefront

Features

Integrations

Deployment

​Gift Card Overview

​Gift Card List

​Status Filtering

Active

Inactive

All

​Creating Gift Cards

​Gift Card Properties

​Gift Card Details

​Basic Information

​Purchase Information

​Transaction History

​Transaction Details

​Balance Changes

​Gift Card Redemption

​Customer Redemption Flow

​Validation Rules

​Partial Redemption

​Managing Gift Cards

​Disabling Gift Cards

​Adjusting Balances

​Extending Expiration

​Gift Card Products

​Creating Gift Card Products

​Gift Card Fulfillment

​Reporting & Analytics

​Gift Card Metrics

​Export Options

Gift Card List

Transaction Report

Redemption Report

Liability Report

​Best Practices

​Troubleshooting

Build docs developers (and LLMs) love

Gift Card Overview

Gift Card List

Status Filtering

Creating Gift Cards

Gift Card Properties

Gift Card Details

Basic Information

Purchase Information

Transaction History

Transaction Details

Balance Changes

Gift Card Redemption

Customer Redemption Flow

Validation Rules

Partial Redemption

Managing Gift Cards

Disabling Gift Cards

Adjusting Balances

Extending Expiration

Gift Card Products

Creating Gift Card Products

Gift Card Fulfillment

Reporting & Analytics

Gift Card Metrics

Export Options

Best Practices

Troubleshooting