Gift Card Products

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €12–25/month

Generated from docs/plan/paid/gift-card-products/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merged from duplicate proposals: “Gift Card Management”

A paid product type for merchants to sell gift cards with custom denominations and expiry dates. Gift cards are digital products delivered via email; customers redeem codes at checkout to reduce order total. Creates new revenue stream without fulfillment, and paid because redemption tracking and fraud prevention require specialized logic.

The problem

I want to sell gift cards — €50, €100, €200 denominations — as impulse purchases. Gift cards are pure revenue with no cost. But managing codes, tracking balances, preventing fraud, and honoring expiry dates is complex. I need a built-in gift card system.

What it does

• Gift card product type: select ‘Gift Card’ when creating product; set denominations (€50, €100, €200)
• Customizable gift cards: customer can set custom amount (€25–€500 range) at checkout
• Gift card generation: when gift card order is placed, unique code is generated (32-char alphanumeric)
• Email delivery: gift card code sent to customer email (or recipient email if ‘gift recipient’ address provided)
• Gift card balance: customers can check balance and redemption history via unique link (no login required)
• Redemption: customer enters gift card code at checkout; balance is deducted from order total
• Expiry: gift cards expire after 2 years (configurable); expired codes show ‘expired’ on check-balance page and rejected at checkout
• Partial redemption: customer can use €30 of €100 gift card; remaining €70 balance is available for next purchase
• Audit trail: log all gift card codes, balance changes, redemptions, refunds, expirations
• Fraud prevention: flag suspicious patterns (100 redemptions in 1 minute, codes guessed sequentially) and alert merchant

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Gift card bundling or tiered gifting — that is gift bundle feature, separate product type.
• Affiliate programs (merchants sell gift cards on third-party sites) — that is affiliate module.
• Gift card resale marketplace — that is marketplace module, separate platform.
• Corporate gift card management (bulk purchase, employee allocation) — that is B2B gifting, separate paid module.
• Gift message or custom card design (printing) — that is media/design module; gift card email is text-only.

Data model

New GIFT_CARD table (gift_card_id, order_id, code (unique, indexed), denomination_minor, balance_minor, created_at, expires_at, is_used). New GIFT_CARD_REDEMPTION table (redemption_id, gift_card_id, redeemed_amount_minor, order_id, redeemed_at). Migration required: none (new tables).

API

• POST /admin/products (create gift card product with min/max amount, expiry_years)
• GET /gift-cards/:code/balance (public: return balance and expiry date, no login required)
• POST /cart (redeem gift card: {gift_card_code, amount_to_redeem})
• POST /admin/gift-cards/:id/refund (merchant refund: restore balance if order refunded)
• GET /admin/gift-cards/report (export all gift card codes, balances, redemption history)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Product create form: product_type=‘Gift Card’. Gift card section: denomination picker (fixed € amounts), min/max custom amount range, expiry years, email template. Gift card admin page: list all codes with balance, redemption history, expiry date, status (active/used/expired/refunded). Check balance and redemption timeline per code. Fraud alert dashboard.

The seam — why this is paid

Paid gift card module owns code generation, balance tracking, redemption logic, expiry enforcement, and fraud detection. Core provides order/payment infrastructure; gift card module consumes payment APIs and adds gifting logic. Paid because redemption and fraud require specialized logic.

Specialized product type with unique fulfillment (digital delivery + redemption). Smaller merchants don’t offer gift cards; mid-market shops justify paid for revenue.

Dependencies

• Product model (core, existing)
• Order management (core, existing)
• Cart system (core, existing)
• Email system (core, for code delivery)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Gift card product ‘Custom Gift Card’ created: €25–€500 custom range, expires after 2 years
• Customer purchases €100 gift card; unique 32-char code generated (e.g., GC-ABCD-EFGH-IJKL)
• Email sent to recipient with code and balance-check link; no login required
• Recipient checks balance: shows €100 remaining, expiry date (2-year countdown)
• Recipient redeems €30 on first order; gift card balance becomes €70; redemption logged
• Gift card code entered again on second order; balance shows €70; €40 redeemed, €30 remains
• Gift card expires (2 years pass); check-balance page shows ‘Expired on 2026-01-15’; redemption at checkout rejected with ‘Gift card expired’
• Original order refunded; gift card balance restored (if refund applies)

Risks

If gift card codes are predictable (sequential), attackers guess and redeem codes belonging to others. Mitigate: use cryptographically random codes (128+ bit entropy). If balance is not decremented atomically, double-redemption occurs (two orders both use €100 from €100 gift card). Mitigate: row-lock balance during redemption transaction. If expiry is not enforced, expired gift cards are redeemed (liability). Mitigate: check expiry on every redemption attempt, reject if expired. If gift card refund is not atomic, refund happens but balance isn’t restored (merchant loses track). Mitigate: link refund to gift card record, atomically restore balance on order refund.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.