Athenian Gift Cards

Developer starting point

This baseline documents gift-card code and balance workflows. It does not claim a payment, redemption, refund, or customer balance mutation has been exercised.

Administrative Workflow

1. Configure gift card settings

Admins can access WooCommerce → Gift Card Settings to configure global gift card behavior:

• Default Expiration Days — 0 means gift cards never expire. A positive value gives newly issued cards an expiration date based on the payment date.
• Allow Partial Redemptions — when enabled, a gift card can apply up to the remaining order total. When disabled, a card only applies if its balance is greater than or equal to the order total.

2. Configure gift card design

Admins can access the Designer tab or the Gift Card Designer submenu to configure presentation settings:

• Active template ID.
• Logo URL.
• Accent color.
• Email background color.
• Card background color.
• Custom CSS.
• Optional sender name override.
• Optional sender email override.

The current implementation ships with a default PHP email template and interface-based extension points for future template providers, renderers, and email senders.

3. Mark products as gift cards

On WooCommerce product edit screens, admins can mark simple or variable products as gift card products using the _ath_is_giftcard product option. A dedicated Gift Card product tab also supports:

• _ath_giftcard_default_to — default recipient email.
• _ath_giftcard_note — default message.

These defaults are useful for internal cards, promotional campaigns, or administrative issuance flows where the purchaser does not provide recipient details.

4. Manage issued gift cards

Issued gift cards are stored as private ath_giftcard posts and exposed under WooCommerce. Admins can review and edit:

• Code.
• Status: active, disabled, or expired.
• Initial balance.
• Current balance.
• Currency.
• Expiration date.
• Recipient name.
• Recipient email.
• Message.
• Issuing order reference.

The list table adds operational columns for balance, status, expiration, and recipient.

Customer Purchase Workflow

1. Customer opens a product marked as a gift card.
2. Product page displays optional gift card recipient fields.
3. Customer enters recipient name, recipient email, and message.
4. Fields are stored on the cart item and displayed in cart/checkout item data.
5. During checkout order creation, the recipient metadata is persisted onto the order line item.
6. When the order moves to processing or completed, the plugin issues gift card code(s).
7. The recipient email is used when provided; otherwise, the purchaser billing email receives the gift card email.
8. Issued card details are stored on the order under _ath_gc_issued_cards.

Customer Redemption Workflow

1. Customer enters a gift card code in the cart or checkout gift card box.
2. AJAX validates the nonce, normalizes the code, and looks up the gift card by secure code hash.
3. The card must exist, be active, not expired, and have a positive balance.
4. Valid codes are stored in the WooCommerce session under ath_gc_codes.
5. Cart totals are recalculated.
6. During woocommerce_cart_calculate_fees, the plugin applies available gift card value as negative, non-taxable WooCommerce fees.
7. Applied values are stored in session under ath_gc_applied.
8. During order creation, codes and applied amounts are saved on the order.
9. When the order reaches processing or completed, the plugin debits the card balances and marks the order as redeemed with _ath_gc_redeemed.

Technical Architecture

Main plugin bootstrap

Primary file:

• athenian-gift-cards.php

The plugin defines version/path constants, declares WooCommerce HPOS compatibility, loads includes/Plugin.php, and boots the plugin on plugins_loaded at priority 5.

Core constants:

• ATH_GC_VERSION — 1.0.5
• ATH_GC_FILE
• ATH_GC_DIR
• ATH_GC_URL

Platform requirements declared in the plugin header:

• WordPress 6.2+
• PHP 8.0+
• WooCommerce 7.0+
• Tested with WooCommerce up to 9.7

Core class map

| Area | Class/File | Purpose | |---|---|---| | Bootstrap | Athenian\GiftCards\Plugin | Loads includes and wires admin, frontend, checkout, issuance, and APC integration modules. | | Utility | Athenian\GiftCards\Util | Code generation, hashing, money formatting, permission checks, and Woo request helpers. | | Data model | Athenian\GiftCards\Model\GiftCard | Object wrapper for gift card CPT records, balance updates, code lookup, issuance, and debit logic. | | CPT registration | Athenian\GiftCards\Admin\CPT | Registers the private ath_giftcard post type. | | Admin UI | Athenian\GiftCards\Admin\Admin_UI | WooCommerce admin menus, settings screen, gift card metabox, list table columns, and save handling. | | Product UI | Athenian\GiftCards\Admin\Product_UI | Adds gift card product flag, gift card product tab, default recipient, and default message fields. | | Issuance | Athenian\GiftCards\Issuance\Issuer | Captures purchase fields, persists order item meta, and issues cards on paid order statuses. | | Redemption | Athenian\GiftCards\Checkout\Redeemer | Cart/checkout UI, AJAX apply/remove, fee application, order meta capture, and final balance debit. | | Frontend | Athenian\GiftCards\Frontend\Shortcodes | Registers gift card balance shortcode. | | Email | Athenian\GiftCards\Emails\Mailer | Sends gift card emails using DesignManager when available, with a legacy fallback. | | Design | Athenian\GiftCards\Design\DesignManager | Email template, renderer, sender, and design settings orchestration. | | APC integration | Athenian\GiftCards\Integrations\APC | Optionally enqueues APC/token bridge styling when Athenian Platform Core is available. |

Data Model

Custom post type

The plugin registers a private custom post type:

• ath_giftcard

Key registration details:

• public: false
• show_ui: true
• show_in_menu: false
• supports: title
• Admin menu is manually added under WooCommerce.

Gift card metadata

| Meta key | Purpose | |---|---| | _ath_gc_code | Human-readable gift card code. | | _ath_gc_code_hash | SHA-256 hash of normalized code used for lookup. | | _ath_gc_initial | Original issued amount. | | _ath_gc_balance | Current remaining balance. | | _ath_gc_currency | Currency code. | | _ath_gc_status | active, disabled, or expired. | | _ath_gc_purchaser_user_id | User ID of purchaser when available. | | _ath_gc_recipient_email | Recipient email. | | _ath_gc_recipient_name | Recipient name. | | _ath_gc_message | Purchaser message. | | _ath_gc_order_id | Order that issued the card. | | _ath_gc_expires_at | Expiration date in Y-m-d format. | | _ath_gc_redeemed_at | Timestamp set when balance reaches zero. | | _ath_gc_debit | Repeated debit history rows containing timestamp, order ID, amount, before, and after values. |

Product metadata

| Meta key | Purpose | |---|---| | _ath_is_giftcard | Marks a product as a gift card product. | | _ath_giftcard_default_to | Optional default recipient email. | | _ath_giftcard_note | Optional default message. |

Cart item metadata

| Cart item key | Purpose | |---|---| | ath_gc_recipient_name | Recipient name entered on product page. | | ath_gc_recipient_email | Recipient email entered on product page. | | ath_gc_message | Gift message entered on product page. | | ath_gc_hash | Unique hash to prevent separate gift card lines from merging when recipient data differs. |

Order metadata

| Meta key | Purpose | |---|---| | _ath_gc_codes | Applied gift card codes captured at checkout. | | _ath_gc_applied | Applied amount per code. | | _ath_gc_redeemed | Flag showing redemption has been captured. | | _ath_gc_redeemed_total | Total gift card value debited for the order. | | _ath_gc_issued | Flag showing gift cards have been issued for the order. | | _ath_gc_issued_cards | Issued card details: post ID, code, amount, currency, and recipient. | | _ath_stored_value_tenders | Shared JSON tender list used by Athenian stored-value modules. |

Order item metadata

| Meta key | Purpose | |---|---| | ath_gc_recipient_name | Recipient name persisted from the cart item. | | ath_gc_recipient_email | Recipient email persisted from the cart item. | | ath_gc_message | Gift message persisted from the cart item. |

Email & Designer Architecture

The plugin includes a design-oriented email subsystem rather than relying only on a single static template.

Design contracts

The design layer defines interfaces for:

• TemplateProviderInterface
• RendererInterface
• EmailSenderInterface

Default implementations include:

• DefaultTemplateProvider
• PhpTemplateRenderer
• WpMailSender

This makes the gift card email system extensible for future JSON templates, alternate renderers, external mail services, preview builders, or PDF gift card attachments.

Default template

The default email body template lives at:

• templates/giftcard/default.php

The legacy fallback email template lives at:

• templates/emails/giftcard.php

The renderer can wrap the gift card body with WooCommerce email header/footer templates when WooCommerce email helpers are available.

Design settings

Stored in:

• ath_gc_design

Supported keys:

• template_id
• logo_url
• accent
• bg
• card_bg
• custom_css
• sender_name
• sender_email

Hooks & Integration Points

WooCommerce product/admin hooks

| Hook | Purpose | |---|---| | product_type_options | Adds the product-level Gift Card checkbox. | | woocommerce_product_options_general_product_data | Adds gift card flag in general product data. | | woocommerce_product_data_tabs | Adds dedicated Gift Card tab. | | woocommerce_product_options_ath_giftcard | Renders default recipient/message settings. | | woocommerce_process_product_meta | Saves gift card product metadata. |

WooCommerce purchase/issuance hooks

| Hook | Purpose | |---|---| | woocommerce_before_add_to_cart_button | Renders recipient fields for gift card products. | | woocommerce_add_cart_item_data | Captures recipient/message cart metadata. | | woocommerce_get_item_data | Displays recipient information in cart/checkout. | | woocommerce_checkout_create_order_line_item | Persists gift card item metadata to order items. | | woocommerce_order_status_processing | Issues gift cards and captures redemptions. | | woocommerce_order_status_completed | Issues gift cards and captures redemptions. |

WooCommerce redemption hooks

| Hook | Purpose | |---|---| | wp_enqueue_scripts | Enqueues cart/checkout frontend assets. | | woocommerce_cart_totals_after_order_total | Displays gift card apply/remove UI in cart totals. | | woocommerce_review_order_after_order_total | Displays gift card apply/remove UI in checkout order review. | | wc_ajax_ath_apply_giftcard | AJAX handler for applying codes. | | wc_ajax_ath_remove_giftcard | AJAX handler for removing codes. | | woocommerce_cart_calculate_fees | Applies redeemed gift card value as negative cart fees. | | woocommerce_checkout_create_order | Persists applied cards to order metadata. |

Athenian platform hooks

| Hook | Event | |---|---| | ath_stored_value_ledger_entry | Fires on gift card issuance and redemption capture. |

Ledger event examples:

• issue — positive amount when a gift card is created.
• redeem_capture — negative amount when gift card value is debited against an order.

Design filters

| Filter | Purpose | |---|---| | ath_gc_design_template_provider | Replace or extend template provider. | | ath_gc_design_renderer | Replace email renderer. | | ath_gc_design_email_sender | Replace email sender. |

Shortcodes

The plugin registers a simple balance shortcode:

• '[ath_giftcard_balance code="GC-XXXX-XXXX-XXXX-XXXX"]'

This shortcode looks up the card by code, checks expiration, and returns the formatted balance. It is best suited for controlled support pages, account pages, or internal test flows because it requires the code as an attribute.

Athenian Platform Core Integration

Athenian Gift Cards has an optional integration with Athenian Platform Core. When APC asset helpers are available, the plugin enqueues assets/css/apc-bridge.css to ensure the gift card frontend inherits Athenian token fallbacks.

The deeper APC alignment is in the shared stored-value data model:

• Gift card usage is added to _ath_stored_value_tenders.
• Tender lines use the same general format as the Store Credits & Rewards plugin.
• Issuance and redemption emit ledger-style hooks for future accounting or reporting listeners.

Example tender line structure:

{
  "type": "gift_card",
  "ref": "12345",
  "amount": 25.00,
  "label": "Gift Card GC-...XYZ"
}

Security & Data Integrity Notes

• Gift card codes are normalized to uppercase before storage/session comparison.
• Code lookup uses SHA-256 hashes stored in _ath_gc_code_hash.
• Admin saves use nonces and permission checks.
• AJAX apply/remove actions require a frontend nonce.
• Gift card balances are debited only after order status transitions, not while a cart is still pending.
• _ath_gc_redeemed prevents duplicate redemption capture for the same order.
• _ath_gc_issued prevents duplicate issuance for the same paid order.
• Gift card record management requires manage_woocommerce or manage_options.