Gift Cards

Overview

Gift Cards allow customers to purchase prepaid cards that can be redeemed for orders. Great for gifts and customer retention.

Key Purpose: Sell and manage prepaid gift cards.

Purpose

This page lets you enable and configure gift card functionality so customers can purchase prepaid cards and recipients can redeem them as payment at checkout.

Key Concepts

Gift Card Record: Stored in the transactions collection with a "gift_card" model type, each record tracks the purchase date, last used date, initial value, current balance, and status.
Gift Card Code: A unique auto-generated code in either numeric (1234-5678-9012-3456) or alphanumeric (ABCD-1234-EFGH-5678) format that the recipient enters at checkout to apply the card balance.
Balance Management: The gift card balance decreases with each use; partial redemptions leave a remaining balance for future orders, and the system tracks each transaction against the card.
Customer Association: Gift cards are linked to a customer-vendor ID, allowing the backoffice to display a customer's gift card history via the customer detail datatable.
Soft Delete: Gift card records use soft deletion, meaning cancelled or removed cards are marked as deleted rather than permanently erased from the database.

Actions

Enable Gift Cards

Toggle the gift card feature on or off, configure preset amounts, allow custom amounts with min/max bounds, set the expiry period in months, and choose the code format.

Purchase a Gift Card

Customers select an amount (preset or custom), optionally enter recipient details and a personal message, complete payment, and receive the generated gift card code via email.

Redeem a Gift Card

At checkout, the customer enters a gift card code; the system validates the code, checks the balance and expiry, and applies the available balance to the order total.

Location

Backoffice Route: /marketing/gift-cards
Backend Controller: app/Http/Controllers/Api/GiftCardController.php
Vue Component: src/views/marketing/gift-cards/index.vue

Concepts

Gift Card

A prepaid card with a balance that can be used for purchases.

Gift Card Code

Unique code used to redeem the gift card.

Balance

Remaining value on the gift card.

Gift Card Settings

Gift Cards Enabled

Property	Value
Field ID	`enabled`
Label	Enable Gift Cards
Type	Toggle
Default	false

Description: Master switch to enable gift card functionality.

Available Amounts

Property	Value
Field ID	`amounts`
Label	Gift Card Amounts
Type	Array of numbers
Default	[25, 50, 75, 100]

Description: Preset amounts customers can purchase.

Examples:

[10, 25, 50, 100]
[20, 50, 100, 150, 200]

Custom Amount

Property	Value
Field ID	`allow_custom_amount`
Label	Allow Custom Amount
Type	Toggle
Default	false

Description: Allow customers to enter custom gift card amount.

Minimum Amount

Property	Value
Field ID	`min_amount`
Label	Minimum Amount
Type	Currency
Default	10
Depends On	allow_custom_amount = true

Description: Minimum custom gift card amount.

Maximum Amount

Property	Value
Field ID	`max_amount`
Label	Maximum Amount
Type	Currency
Default	500
Depends On	allow_custom_amount = true

Description: Maximum custom gift card amount.

Expiry Period

Property	Value
Field ID	`expiry_months`
Label	Expiry Period
Type	Number
Unit	Months
Default	12
Validation	min: 1

Description: How long gift cards are valid after purchase.

Code Format

Property	Value
Field ID	`code_format`
Label	Code Format
Type	Select
Options	numeric, alphanumeric
Default	alphanumeric

Description: Format of generated gift card codes.

Examples:

Numeric: 1234-5678-9012-3456
Alphanumeric: ABCD-1234-EFGH-5678

Gift Card Fields

Gift Card Code

Property	Value
Field ID	`code`
Label	Code
Type	String
Auto-generated	Yes

Description: Unique code for the gift card.

Initial Value

Property	Value
Field ID	`initial_value`
Label	Initial Value
Type	Currency

Description: Original amount loaded on the card.

Current Balance

Property	Value
Field ID	`balance`
Label	Balance
Type	Currency

Description: Remaining balance on the card.

Status

Property	Value
Field ID	`status`
Label	Status
Type	Select
Options	active, redeemed, expired, cancelled

Description: Current status of the gift card.

Statuses:

Active: Can be used
Redeemed: Fully used (balance = 0)
Expired: Past expiry date
Cancelled: Manually cancelled

Purchase Date

Property	Value
Field ID	`purchased_at`
Label	Purchase Date
Type	DateTime

Description: When the gift card was purchased.

Expiry Date

Property	Value
Field ID	`expires_at`
Label	Expiry Date
Type	DateTime

Description: When the gift card expires.

Purchaser

Property	Value
Field ID	`purchaser`
Label	Purchased By
Type	Object

Description: Customer who purchased the gift card.

Recipient

Property	Value
Field ID	`recipient`
Label	Recipient
Type	Object

Description: Intended recipient (for gifting).

Fields:

name - Recipient name
email - Recipient email
message - Personal message

Business Logic

Purchase Flow

Customer selects gift card amount
        │
        ▼
Enter recipient details (optional)
        │
        ▼
Complete payment
        │
        ▼
Generate unique code
        │
        ▼
Send gift card:
├── To purchaser (confirmation)
└── To recipient (if provided)

Redemption Flow

Customer enters gift card code at checkout
        │
        ▼
Validate code:
├── Not found → "Invalid gift card"
├── Expired → "Gift card expired"
├── No balance → "No balance remaining"
│
└── Valid → Show available balance
        │
        ▼
Apply to order:
├── Balance >= Order total → Pay full amount
└── Balance < Order total → Pay partial, remaining due
        │
        ▼
Deduct from gift card balance

Balance Calculation

Order Total: €35.00
Gift Card Balance: €50.00

Applied: €35.00
Remaining Balance: €15.00

OR

Order Total: €35.00
Gift Card Balance: €20.00

Applied: €20.00
Remaining to Pay: €15.00 (other payment method)

Customer Impact

Purchasing

Select gift card amount
Enter recipient details (optional)
Add personal message (optional)
Complete payment
Receive gift card code via email

Redeeming

Enter gift card code at checkout
Balance applied to order
Pay remaining balance (if any)
Receive updated balance info

Checking Balance

Enter code on website
View remaining balance
See expiry date

Relations

Depends On

Payments: For purchasing gift cards

Affects

Transactions: Gift card payments
Reports: Gift card sales and redemptions

Business Rules

Gift cards are stored as records in the transactions collection with model type "gift_card" and use the tenant database connection, meaning they are scoped per merchant.
Each gift card has a configurable expiry period (in months from purchase); once expired, the card status changes and the remaining balance cannot be used.
Gift card statuses follow a lifecycle: active (usable), redeemed (balance reaches zero), expired (past expiry date), or cancelled (manually disabled by merchant).
When a gift card balance is less than the order total, the system applies a partial payment and the customer must pay the remaining amount with another payment method.
Gift card records support soft deletion, so cancelled or removed cards remain in the database for audit purposes and can potentially be restored.

FAQs

"Can a gift card be used across multiple orders?" Yes, as long as the card has remaining balance and has not expired; each order deducts the applied amount from the card balance.
"What happens if the gift card balance exceeds the order total?" The system applies only the order total amount from the gift card, and the remaining balance stays on the card for future use.
"Can a customer buy a gift card for themselves?" Yes, the recipient field is optional; if left blank, the purchaser receives the gift card code directly.
"Is there a maximum amount for gift cards?" Yes, if custom amounts are enabled, the system enforces the configured maximum amount (default 500); preset amounts are fixed choices defined by the merchant.
"Can a merchant manually cancel a gift card?" Yes, the gift card status can be set to "cancelled" which prevents further redemption while keeping the record for audit history.

Troubleshooting

Problem: Gift card code not working

Causes:

Code entered incorrectly
Gift card expired
No balance remaining
Gift card cancelled

Solutions:

Check code spelling
Verify expiry date
Check balance
Contact support

Problem: Balance incorrect

Causes:

Previous redemption
Partial use
System error

Solutions:

Check transaction history
Review usage log
Manual adjustment if needed

Problem: Gift card email not received

Causes:

Wrong email address
Spam filter
Email service issue

Solutions:

Verify email address
Check spam folder
Resend gift card email

Examples

Gift Card Settings

json

{
  "enabled": true,
  "amounts": [25, 50, 75, 100],
  "allow_custom_amount": true,
  "min_amount": 10,
  "max_amount": 250,
  "expiry_months": 12,
  "code_format": "alphanumeric"
}

Gift Card Record

json

{
  "code": "GIFT-ABCD-1234-EFGH",
  "initial_value": 50.00,
  "balance": 35.50,
  "status": "active",
  "purchased_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-01-15T23:59:59Z",
  "purchaser": {
    "name": "Jan de Vries",
    "email": "jan@example.com"
  },
  "recipient": {
    "name": "Marie de Vries",
    "email": "marie@example.com",
    "message": "Happy Birthday! Enjoy a nice dinner on me."
  },
  "transactions": [
    {
      "date": "2024-02-01",
      "order_id": "1234",
      "amount": -14.50,
      "balance_after": 35.50
    }
  ]
}

Gift Card Email Template

🎁 You've received a gift card!

Hi Marie,

Jan de Vries has sent you a €50.00 gift card 
for Mario's Restaurant!

Personal message:
"Happy Birthday! Enjoy a nice dinner on me."

Your Gift Card Code:
╔═══════════════════════════╗
║  GIFT-ABCD-1234-EFGH     ║
╚═══════════════════════════╝

How to use:
1. Order online at marios-restaurant.com
2. Enter your code at checkout
3. Enjoy your meal!

Valid until: January 15, 2025

Questions? Contact us at info@marios.com

Checkout with Gift Card

Order Summary:
─────────────────────────────
Margherita Pizza (L)    €15.50
Garlic Bread             €4.50
2x Cola                  €5.00
─────────────────────────────
Subtotal                €25.00
Delivery Fee             €3.50
─────────────────────────────
Total                   €28.50

Gift Card Applied:
GIFT-ABCD-1234-EFGH    -€28.50
(Balance: €35.50 → €7.00)
─────────────────────────────
Amount Due               €0.00

Gift Cards ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Enable Gift Cards ​

Purchase a Gift Card ​

Redeem a Gift Card ​

Location ​

Concepts ​

Gift Card ​

Gift Card Code ​

Balance ​

Gift Card Settings ​

Gift Cards Enabled ​

Available Amounts ​

Custom Amount ​

Minimum Amount ​

Maximum Amount ​

Expiry Period ​

Code Format ​

Gift Card Fields ​

Gift Card Code ​

Initial Value ​

Current Balance ​

Status ​

Purchase Date ​

Expiry Date ​

Purchaser ​

Recipient ​

Business Logic ​

Purchase Flow ​

Redemption Flow ​

Balance Calculation ​

Customer Impact ​

Purchasing ​

Redeeming ​

Checking Balance ​

Relations ​

Depends On ​

Affects ​

Related Features ​

Business Rules ​

FAQs ​

Troubleshooting ​

Problem: Gift card code not working ​

Problem: Balance incorrect ​

Problem: Gift card email not received ​

Examples ​

Gift Card Settings ​

Gift Card Record ​

Gift Card Email Template ​

Checkout with Gift Card ​

Gift Cards

Overview

Purpose

Key Concepts

Actions

Enable Gift Cards

Purchase a Gift Card

Redeem a Gift Card

Location

Concepts

Gift Card

Gift Card Code

Balance

Gift Card Settings

Gift Cards Enabled

Available Amounts

Custom Amount

Minimum Amount

Maximum Amount

Expiry Period

Code Format

Gift Card Fields

Gift Card Code

Initial Value

Current Balance

Status

Purchase Date

Expiry Date

Purchaser

Recipient

Business Logic

Purchase Flow

Redemption Flow

Balance Calculation

Customer Impact

Purchasing

Redeeming

Checking Balance

Relations

Depends On

Affects

Related Features

Business Rules

FAQs

Troubleshooting

Problem: Gift card code not working

Problem: Balance incorrect

Problem: Gift card email not received

Examples

Gift Card Settings

Gift Card Record

Gift Card Email Template

Checkout with Gift Card