Get Started with Aeion Gift Cards

Go to Commerce → Gift Cards → Issue Gift Card or use the API.

Purchase Gift Card (API):

bash POST /giftcards/purchase { "amount": 50.00, "currency": "USD", "quantity": 1, "senderName": "John Smith", "senderEmail": "john@example.com", "recipientName": "Jane Doe", "recipientEmail": "jane@example.com", "personalMessage": "Happy birthday! Enjoy the coffee.", "deliveryMethod": "email", "expirationMonths": 12 }

Response:

typescript { "cards": [ { "id": "gc-xxx", "code": "GC-9G4F-X2P1-MQRB", "amount": 50.00, "formattedAmount": "$50.00", "currency": "USD", "expiresAt": "2027-05-11T00:00:00Z" } ], "totalAmount": 50.00, "formattedTotal": "$50.00", "status": "pending_payment", "message": "Complete payment to activate gift cards" }

Code Format: A short prefix followed by grouped alphanumeric characters, e.g. GC-9G4F-X2P1-MQRB PIN: 4-digit numeric, AES-256-GCM encrypted at rest Status: pending → after payment → active

Generate Bulk Codes (API):

bash POST /giftcards/bulk-generate { "quantity": 1000, "amount": 5.00, "currency": "USD", "batchPrefix": "PR", "source": "holiday_promo_2026", "templateId": "template-xxx", "expirationMonths": 1 }

Response:

typescript { "batchId": "batch_01HV3M7K9X...", "quantity": 1000, "amount": 5.00, "totalValue": 5000.00, "cards": [ { "id": "gc-xxx", "code": "PR-9G4F-X2P1-MQRB" }, { "id": "gc-yyy", "code": "PR-N7K2-H5W8-TXLC" } // ... 998 more ] }

Promotional Prefix: PR for bulk promo codes, GC for standard, SC for store credit wallets

After payment is confirmed, activate the gift card.

Activate (API):

bash POST /giftcards/{cardId}/activate { "paymentTransactionId": "txn_stripe_xxx", "orderId": "order-xxx" }

Response:

typescript { "status": "active", "code": "GC-9G4F-X2P1-MQRB" }

Activation Process:

1. Status transitions from pending to active
2. An activation timestamp is recorded
3. An activation transaction is logged with a unique idempotency key
4. A delivery event fires for scheduled or immediate recipient notification

Scheduled Delivery:

bash POST /giftcards/purchase { "amount": 75.00, "recipientEmail": "jane@example.com", "deliveryMethod": "email", "scheduledDelivery": "2026-06-15T09:00:00Z" // Birthday gift }

A background job engine processes scheduled deliveries automatically once the scheduled time arrives.

Reload Balance (API):

bash POST /giftcards/reload { "code": "GC-9G4F-X2P1-MQRB", "pin": "1234", "amount": 25.00, "paymentMethodId": "pm_stripe_xxx" }

Response:

typescript { "previousBalance": 20.00, "addedAmount": 25.00, "newBalance": 45.00, "formattedBalance": "$45.00" }

Concurrency-Safe: Reloads are applied atomically, with checks that block canceled/expired/non-reloadable cards and enforce any configured maximum balance cap. A confirmed final balance is always returned, even under concurrent requests.

Auto-Reload Configuration:

typescript // Configure on card record { "autoReloadEnabled": true, "autoReloadAmount": 25.00, // Reload $25 "autoReloadThreshold": 10.00, // Trigger when balance ≤ $10 "autoReloadPaymentMethodId": "pm_xxx" }

Triggered automatically when the card balance drops to or below the configured threshold — the balance is topped up and a transaction is logged.

Transfer to Another Person (API):

bash POST /giftcards/transfer { "code": "GC-9G4F-X2P1-MQRB", "pin": "1234", "recipientEmail": "bob@example.com", "recipientName": "Bob Smith", "message": "Here's a gift card for you!" }

Response:

typescript { "message": "Gift card transferred to bob@example.com", "newCode": "GC-N7K2-H5W8-TXLC", "balance": 45.00 }

Transfer Process:

• Old code (GC-9G4F-X2P1-MQRB) invalidated
• New code (GC-N7K2-H5W8-TXLC) generated for recipient
• Transaction logged with sender/recipient details
• Email sent to new recipient with new code and balance

Issue Store Credit (API):

bash POST /giftcards/issue-store-credit { "customerId": "user-xxx", "amount": 75.00, "currency": "USD", "reason": "Return - Item not as described", "orderId": "order-return-xxx", "notes": "Ticket #8492 - Customer Support Resolution" }

Response:

typescript { "data": { "wallet": { "id": "gc-yyy", "code": "SC-N7K2-H5W8-TXLC", "balance": 75.00, "currency": "USD" } } }

Wallet Behavior:

• If customer already has a store-credit wallet → increment existing balance atomically
• If no wallet → create new one with prefix SC
• Transaction logged with reason and originating order for audit purposes

Review Analytics (Admin):

bash GET /giftcards/analytics

Response:

typescript { "stats": { "totalCards": 5420, "activeCards": 3100, "emptyCards": 1200, "expiredCards": 120, "totalIssued": 270000.00, "totalRedeemed": 189000.00, "outstandingBalance": 81000.00, "averageCardValue": 49.82, "formattedTotalIssued": "$270,000.00", "formattedTotalRedeemed": "$189,000.00", "formattedOutstandingBalance": "$81,000.00", "redemptionRate": 70 }, "recentTransactions": [...] }

Redemption Rate: total redeemed ÷ total issued × 100

Liability Report:

• Outstanding Balance = total unredeemed value (liability)
• Purchase type (digital / promotional / store credit) distinguishes liability from breakage for CFO reporting

Transaction History (API):

bash GET /giftcards/{cardId}/transactions?limit=50&offset=0

Response:

typescript { "transactions": [ { "type": "purchase", "amount": 50.00, "balanceAfter": 50.00, "createdAt": "2026-05-01T10:00:00Z" }, { "type": "redemption", "amount": -30.00, "balanceAfter": 20.00, "createdAt": "2026-05-05T14:30:00Z" }, { "type": "reload", "amount": 25.00, "balanceAfter": 45.00, "createdAt": "2026-05-10T09:00:00Z" } ] }