Gift Certificates

Customers can purchase digital gift certificates with themed designs, which recipients redeem as payment during checkout. The admin panel supports creating, managing, and bulk-importing certificates.

Architecture

Purchase Flow

const GiftCertificatePurchaseSchema = z.object({
  purchaserName: z.string().min(1),
  purchaserEmail: z.string().email(),
  recipientName: z.string().min(1),
  recipientEmail: z.string().email(),
  amount: z.number().positive().min(1),
  theme: z.enum(['BIRTHDAY', 'BOY_CELEBRATION', 'CHRISTMAS', 'GENERAL', 'GIRL']),
  message: z.string().optional(),
  nonRefundableAgreement: z.boolean().refine((val) => val === true),
})

Certificate Code Generation

Codes use a collision-resistant format with retry loop:

async function generateGiftCertificateCode(): Promise<string> {
  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
  let exists = true
  while (exists) {
    const part1 = Array.from({ length: 4 }, () =>
      chars[Math.floor(Math.random() * chars.length)]
    ).join('')
    const part2 = Array.from({ length: 4 }, () =>
      chars[Math.floor(Math.random() * chars.length)]
    ).join('')
    code = `JMS-GC-${part1}-${part2}`
    exists = !!(await prisma.giftCertificate.findUnique({ where: { code } }))
  }
  return code
}

Themes

Balance Check

The /gift-certificates/balance page allows anyone to check remaining balance by entering their certificate code.

Checkout Redemption

During checkout, customers can apply a gift certificate code via POST /api/checkout/apply-gift-certificate. The endpoint:

1. Looks up the certificate by code
2. Validates it is active and has remaining balance
3. Deducts the applied amount from the certificate balance
4. Reduces the order total accordingly

CSV Import

The importGiftCertificates() function in lib/gift-certificates/import.ts supports bulk import from CSV with Zod validation per row. Failed rows are reported with row numbers and error messages without blocking successful imports.