Athenian Store Credits & Rewards

Developer starting point

This baseline documents store-credit and reward architecture. It does not claim a live balance mutation, refund, checkout redemption, or customer account flow has been exercised.

Customer Workflow

Customer Earns Points

1. Customer completes a WooCommerce order.
2. On completed status, the plugin calculates purchase points from order subtotal.
3. Optional first-purchase and lifetime-spend rewards are evaluated.
4. Points are added to the customer balance.
5. A points ledger entry is written.

Customer Converts Points

1. Customer opens My Account > Credits.
2. Customer enters the number of points to convert.
3. Plugin validates the conversion against current balance and configured ratio.
4. Points are debited.
5. Store credit is credited.
6. Both ledger trails are updated.

Customer Applies Credit

1. Customer enables the apply-credit toggle in the Credits panel.
2. Plugin stores that preference in WooCommerce session data.
3. During cart calculation, the plugin checks customer balance and cart total.
4. Store credit is applied as a negative fee labeled Store Credit.
5. The pending credit amount is stored in session for checkout/order persistence.

Order Captures Store Credit

1. Order is created at checkout.
2. Applied credit amount is persisted to order meta.
3. Shared stored-value tender metadata is written to the order.
4. When the order moves to processing or completed, the plugin debits the customer balance.
5. The order is marked as captured to prevent duplicate deduction.
6. Session apply-credit flags are cleared.

---

Administrator Workflow

Configure Rewards

Administrators can configure:

• Points awarded per currency unit.
• Number of points required to create one unit of store credit.
• Whether the customer-facing My Account Credits widget is visible.
• Per-action point overrides for registered reward actions.

Review Program Totals

The overview dashboard provides current operational totals for outstanding credit and points, including seven-day net movement summaries.

Adjust a Customer Manually

Administrators can enter a customer email or user ID, then apply:

• Positive or negative store-credit adjustments.
• Positive or negative points adjustments.
• Optional adjustment notes.

Manual adjustments are written to the relevant balance and ledger surfaces.

Audit Ledger Rows

Credit and points ledgers can be viewed from the admin tabs. Ledger entries include user, order/action reference, amount/points, direction, and timestamp. Bulk deletions trigger balance recalculation for affected users, which is useful for correcting test data or cleaning invalid entries.

---

Technical Architecture

Plugin Header

Main plugin file:

athenian-store-credits-rewards.php

Header identity:

• Plugin Name: Athenian Store Credits & Customer Rewards
• Version: 0.1.0
• Text Domain: athenian-credits-rewards
• Namespace: Athenian\CreditsRewards

The plugin boots on plugins_loaded only when WooCommerce is available.

Core Classes

| Class | Purpose | | --- | --- | | Activator | Creates ledger tables and registers the My Account endpoint on activation. | | Plugin | Main singleton container that wires all subsystems together. | | Actions_Registry | Central registry of rewardable action definitions and extension filter. | | Store_Credit_Manager | Store-credit balances, cart application, order persistence, capture, and tender metadata. | | Rewards_Manager | Points balances, point ledger entries, purchase/review rewards, custom action triggers, and conversion. | | Admin_UI | WooCommerce admin page, settings, stats, manual adjustment, user profile tools, and ledger tabs. | | MyAccount_UI | Customer Credits endpoint, account panel, apply-credit toggle, and point conversion form. | | GraphQL | Optional WPGraphQL schema integration. | | Admin_Credit_Ledger_Table | WP_List_Table implementation for store-credit ledger rows. | | Admin_Points_Ledger_Table | WP_List_Table implementation for points ledger rows. |

File Structure

athenian-store-credits-rewards.php
assets/
  css/
    account.css
    admin.css
  js/
    admin.js
docs/
  ascr-marketing-document.md
  athenian-platform-marketing.md
  athenian-platform-technical.md
includes/
  class-actions-registry.php
  class-activator.php
  class-admin-ui.php
  class-graphql.php
  class-myaccount-ui.php
  class-plugin.php
  class-rewards-manager.php
  class-store-credit-manager.php
  admin/
    class-ascr-credit-ledger-table.php
    class-ascr-points-ledger-table.php

---

Data Model

User Meta

| Key | Purpose | | --- | --- | | _ascr_credit_balance | Current store-credit balance for the user. | | _ascr_points_balance | Current reward-points balance for the user. | | _ascr_spend_milestones_awarded | Tracks lifetime-spend milestones already awarded. |

Order Meta

| Key | Purpose | | --- | --- | | _ascr_credit_applied_amount | Store credit amount applied to the order. | | _ath_stored_value_tenders | JSON list of stored-value tender lines applied to the order. | | _ascr_credit_captured | Prevents duplicate store-credit capture on paid/fulfilled statuses. |

Options

| Option | Purpose | | --- | --- | | ascr_rewards_settings | Reward configuration, conversion ratio, account widget visibility, action overrides. | | ascr_account_endpoint_rewrite_version | Tracks endpoint rewrite registration state. |

WooCommerce Session Keys

| Key | Purpose | | --- | --- | | ascr_apply_credit | Stores whether customer opted to apply credit to the cart. | | ascr_credit_applied_amount | Stores the pending cart credit amount before order creation. |

Custom Tables

#### wp_ascr_credit_ledger

| Column | Type | Purpose | | --- | --- | --- | | id | BIGINT unsigned | Primary ledger row ID. | | user_id | BIGINT unsigned | Customer/user receiving the credit movement. | | order_id | BIGINT unsigned nullable | Related WooCommerce order where applicable. | | amount | DECIMAL(18,4) | Monetary value of the movement. | | direction | VARCHAR(10) | Credit/debit direction label. | | reason | VARCHAR(191) nullable | Human-readable reason. | | meta | LONGTEXT nullable | JSON-encoded contextual metadata. | | created_at | DATETIME | Ledger entry timestamp. |

#### wp_ascr_points_ledger

| Column | Type | Purpose | | --- | --- | --- | | id | BIGINT unsigned | Primary ledger row ID. | | user_id | BIGINT unsigned | Customer/user receiving the points movement. | | action_key | VARCHAR(100) | Reward action that produced the movement. | | points | BIGINT | Positive or negative points delta. | | meta | LONGTEXT nullable | JSON-encoded contextual metadata. | | created_at | DATETIME | Ledger entry timestamp. |

---

Hooks and Integration Points

WordPress Hooks

| Hook | Usage | | --- | --- | | plugins_loaded | Boots the plugin after WooCommerce is available. | | admin_menu | Adds WooCommerce admin submenu. | | admin_init | Registers plugin settings. | | admin_post_ascr_adjust_user | Handles manual admin balance adjustments. | | show_user_profile / edit_user_profile | Displays user profile balance controls. | | personal_options_update / edit_user_profile_update | Saves user profile balance controls. | | admin_enqueue_scripts | Loads admin CSS/JS for plugin screens. | | init | Registers account endpoint and handles account form POST actions. | | wp_enqueue_scripts | Loads account panel CSS. | | wp_set_comment_status | Awards review points when product reviews are approved. | | graphql_register_types | Registers optional WPGraphQL fields. |

WooCommerce Hooks

| Hook | Usage | | --- | --- | | woocommerce_cart_calculate_fees | Applies store credit to cart as a negative fee. | | woocommerce_checkout_create_order | Persists applied credit and stored-value tender metadata to order. | | woocommerce_order_status_processing | Captures/debits applied credit. | | woocommerce_order_status_completed | Awards purchase points and captures/debits applied credit. | | woocommerce_get_query_vars | Adds the Credits My Account endpoint query var. | | woocommerce_account_menu_items | Adds the Credits menu item. | | woocommerce_account_credits_endpoint | Renders the account panel. |

Extension Hooks

| Hook | Purpose | | --- | --- | | ascr/actions_registry | Filter for registering or modifying reward action definitions. | | ascr/reward_action | Action for external modules to award points using a registered action key. |

Example external reward trigger:

do_action(
    'ascr/reward_action',
    'gallery_upload_approved',
    $user_id,
    [ 'gallery_id' => 123 ]
);

---

Security and Reliability Notes

The implementation includes several practical safeguards:

• Plugin boots only when WooCommerce is active.
• Admin pages and user-profile controls require manage_woocommerce.
• Manual adjustment forms use WordPress nonces.
• My Account actions use nonce validation.
• Admin inputs are sanitized before use.
• Credit capture uses _ascr_credit_captured to prevent duplicate debit.
• Credit application is restricted to logged-in users.
• Cart application is capped by current balance and cart total.
• Ledger table bulk-delete actions recalculate affected user balances.
• WPGraphQL integration is optional and only registers when GraphQL functions are available.

---

Suggested Product Taxonomy

Primary Category

Payments, Pricing & Revenue

Secondary Categories

• WooCommerce Extensions
• Customer Loyalty
• Store Credit
• Customer Accounts
• Commerce Automation
• Athenian Platform Modules

Suggested Tags

• WooCommerce
• WordPress Plugin
• Store Credit
• Customer Rewards
• Loyalty Points
• Account Credit
• Stored Value
• Checkout Credits
• My Account
• WPGraphQL
• Ledger
• Athenian Platform

---

Implementation Notes

Current Strengths

• Compact, readable class structure.
• Ledger-backed design rather than balance-only accounting.
• Native WooCommerce cart/order lifecycle integration.
• Customer self-service through My Account.
• Admin settings and manual correction surfaces.
• Optional WPGraphQL exposure for modern frontends.
• Extensible action registry for future reward events.

Current Limitations / Review Items

• No REST API routes are present in the current source set.
• No shortcode or block interface is present in the current source set.
• Birthday reward is registered in the action registry but no scheduled birthday-award processor is implemented in the inspected code.
• Lifetime milestone logic is simple and fixed at 1000 spend intervals in the current implementation.
• Purchase points are awarded on completed order status; stores with different fulfillment/payment status flows may need status configuration.
• Review rewards should be monitored for duplicate-award behavior if comments are toggled between approved and unapproved states.
• Direct balance setting from user profiles does not necessarily create a ledger row for every overwrite, so operational policy should define when to use manual adjustment versus direct profile edits.

---