Gift Cards

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €19/mo; we hold liability for merchant-issued gift cards

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

Merchants issue gift cards with configurable denominations, balance tracking, and expiry rules. The system prevents resale by linking cards to purchase records, enforces PCI liability limits on stored balances, and provides a redemption flow that reduces customer balance at checkout. Supports both digital (email) and physical (printed code) cards.

The problem

Gift cards increase AOV, but merchants have no system to issue, track, or redeem them without custom code. A customer buys a €50 gift card, gives it to someone who sells it online for €35 (resale loss), and the merchant has no audit trail or loss recovery mechanism.

What it does

• Create gift card product type: merchants define denominations (€25, €50, €100) as variant SKUs
• Issue gift card on purchase: record giftCardCode (16-32 alphanumeric), balance_remaining (in minor units), issued_at, expires_at, associated_customer (optional)
• Prevent resale: if gift card is sold to Customer A, only Customer A’s account can redeem it (check email at redemption time)
• Redemption: customer enters code at checkout → reduce order total by redeemed amount → deduct from gift card balance_remaining
• Store balance in gift_cards table (NOT as a product price): { code, balance_remaining, balance_total, issued_at, redeemed_count, last_used_at }
• Expiry enforcement: gift cards can expire after N days/months (shop setting, default 2 years); expired cards return ‘not valid’ on redemption attempt
• Admin dashboard: ‘Gift Cards’ section shows issued, redeemed, expired, and remaining balance for each code
• Audit log: every redemption attempt (successful or failed) is logged with amount, customer email, order_id

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.

• Multi-currency gift cards (gift card is issued in shop.currency only; multi-currency is a storefront concern, not gift card concern)
• Referral/affiliate gift card bonus (see loyalty-points-program; loyalty owns bonus issuance)
• Physical card printing and fulfillment (merchant provides design, we store it, they print via third party)
• API for third-party gift card resellers (we do not enable resale; fraud liability stays with us)

Data model

Add gift_cards table: { id, code, balance_total, balance_remaining, issued_at, expires_at, customer_email, order_id_issued, redeemed_count, last_used_at, is_expired }. Add giftCard relationship to Order (order.redeemed_gift_cards array). Add shop setting: gift_card_expiry_months (default 24). Schema migration: new table, no risk to existing data.

API

• POST /admin/gift-cards — issue new gift card with denomination and optional customer email
• GET /admin/gift-cards?status=active,redeemed,expired — list gift cards by status
• GET /admin/gift-cards/:code — read balance and redemption history
• POST /checkout/redeem-gift-card — redeem code and reduce order total (returns { balance_remaining, amount_applied })
• GET /account/gift-cards — authenticated customer views their issued/redeemed gift cards

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

Admin

Add ‘Gift Cards’ section in Commerce > Settings. Checkboxes: ‘Enable gift cards’, ‘Allow customer email for purchase’. Denominations input (JSON array: [2500, 5000, 10000]). Expiry months slider (default 24). Admin dashboard: table of all gift cards (code, balance, issued date, status). Quick actions: ‘View redemption history’, ‘Refund balance’ (voids the card).

The seam — why this is paid

Core owns the gift card primitive: data model, balance tracking, and redemption math. Paid module owns: PCI compliance (storing card balances securely, encryption, key rotation), fraud prevention (resale detection, duplicate code generation), and support for lost/stolen card refunds. Merchants cannot issue gift cards without confirming they have appropriate liability insurance.

Support commitment: fraud prevention (resale), PCI liability, balance reconciliation audits

Dependencies

• Product system (gift cards are a special product type)
• Checkout system (redemption flow)
• Audit log system (to track redemptions)

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.

• A merchant issues a €50 gift card (code ABC123); balance_total and balance_remaining both = 5000 (in minor units)
• Customer B redeems code ABC123 for a €35 order; order.redeemed_gift_cards[0].amount_applied = 3500, gift card balance_remaining = 1500
• Attempting to redeem an expired gift card (expires_at < now) returns ‘gift card expired’ error
• If a gift card is issued to customer@example.com, a different customer cannot redeem it (check email at redemption)
• An audit log entry is created for every redemption attempt with gift card code, amount, customer, and order_id
• Admin dashboard shows total balance outstanding and total redeemed to date

Risks

If balance is stored as a float instead of integer, minor-unit math breaks (€50.01 redeemed reduces €50.00 balance to €-0.01). If gift card code is generated non-randomly or with low entropy, brute-force attacks can guess codes. If redemption is not idempotent (customer submits twice), balance is deducted twice. If expiry check is done at issue time instead of redemption time, merchants cannot extend expired cards.

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.