Athenian Coupon Builder

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

Admin Workflow

1. A merchant creates or edits a standard WooCommerce coupon.
2. The Athenian Coupon Conditions meta box appears on the coupon edit screen.
3. The merchant configures advanced eligibility rules such as subtotal bounds, allowed roles, date windows, customer eligibility, and auto-apply behavior.
4. The coupon is saved as a normal WooCommerce shop_coupon post with additional ACB post meta.
5. During cart and checkout validation, Athenian Coupon Builder evaluates the configured rules.
6. If auto-apply is enabled, qualifying coupons can be applied automatically when the customer’s cart meets the conditions.

---

Customer Workflow

Manual Coupon Use

1. Customer enters a coupon code in the cart or checkout flow.
2. WooCommerce begins native coupon validation.
3. Athenian Coupon Builder evaluates the additional conditions.
4. The coupon is accepted only if WooCommerce and ACB rules both pass.

Auto-Applied Coupon Use

1. Customer visits the cart with qualifying products or subtotal.
2. ACB scans published coupons marked for auto-application.
3. Eligible coupons are applied to the cart automatically.
4. The customer sees the promotion without needing to know or enter the coupon code.

---

Technical Architecture

File Structure Observed

athenian-coupon-builder.php
assets/
  css/
    admin.css
  js/
    admin.js
docs/
  athenian-coupon-builder-marketing-document.md
  athenian-platform-marketing.md
  athenian-platform-technical.md
includes/
  class-admin-ui.php
  class-coupon-api.php
  class-coupon-rules.php
  class-plugin.php
  class-rest-probe.php

Bootstrap Flow

1. The main plugin file defines constants and an autoloader for the Athenian\CouponBuilder namespace.
2. On plugins_loaded, the plugin checks whether WooCommerce is active.
3. If WooCommerce is missing, it displays an admin notice and does not boot.
4. If WooCommerce is available, Plugin::instance()->boot() initializes the plugin modules.
5. Admin_UI always boots for admin coupon UI behavior.
6. Coupon_Rules always boots for validation and auto-apply behavior.
7. Rest_Probe boots only during REST requests.

Main Classes

| Class | Responsibility | | --- | --- | | Plugin | Main singleton-style bootstrap and module coordinator. | | Admin_UI | Adds coupon meta box, saves ACB coupon metadata, and enqueues admin assets. | | Coupon_Rules | Enforces coupon conditions and auto-applies eligible coupons. | | Coupon_API | Provides public helper methods for campaign/context metadata. | | Rest_Probe | Registers the debugging REST endpoint for coupon inspection. |

---

WordPress & WooCommerce Integration Points

Actions

| Hook | Method / Purpose | | --- | --- | | plugins_loaded | Bootstrap after WooCommerce is available. | | admin_notices | Display missing WooCommerce notice. | | add_meta_boxes | Add ACB coupon condition meta box. | | save_post_shop_coupon | Persist coupon condition metadata. | | admin_enqueue_scripts | Load admin CSS/JS on coupon edit screens. | | woocommerce_before_cart | Attempt auto-application of eligible coupons. | | rest_api_init | Register the coupon probe REST route. | | acb_coupon_validated | Fires after ACB coupon validation. | | acb_coupon_auto_applied | Fires after ACB auto-applies a coupon. |

Filters

| Filter | Purpose | | --- | --- | | woocommerce_coupon_is_valid | Core runtime validation hook used by ACB. | | acb_coupon_is_valid_for_context | Allows external code to modify ACB validation result. | | acb_coupon_validation_context | Allows external code to enrich the validation context. | | acb_auto_apply_query_args | Allows external code to modify the auto-apply coupon query. | | acb_should_auto_apply_coupon | Allows external code to approve or block auto-application. |

REST Route

| Route | Method | Permission Callback | Purpose | | --- | --- | --- | --- | | /wp-json/ath-coupons/v1/probe | GET | __return_true | Inspect a coupon’s validity, ACB meta, and linkage context. |

---

Data Model

Storage Strategy

The plugin stores all custom configuration as post meta on native WooCommerce shop_coupon posts. It does not create custom tables or custom post types.

ACB Coupon Meta

| Meta Key | Type | Description | | --- | --- | --- | | acb_min_subtotal | Decimal string | Minimum cart subtotal before tax and shipping. | | acb_max_subtotal | Decimal string | Maximum cart subtotal before tax and shipping. | | acb_allowed_roles | Array | WordPress role keys allowed to use the coupon. | | acb_start_date | Date string | Store-timezone campaign start date. | | acb_end_date | Date string | Store-timezone campaign end date. | | acb_auto_apply | Boolean-like string | Whether the coupon should auto-apply when valid. | | acb_new_customers_only | Boolean-like string | Whether only customers with no completed orders may use it. | | acb_first_order_only | Boolean-like string | Whether only first-order customers may use it. | | acb_max_uses_per_user | Integer | ACB usage limit per billing email. | | acb_cart_must_contain_all | Boolean-like string | Captures stricter cart-restriction intent. |

External Context Meta

| Meta Key | Intended Context | | --- | --- | | affp_campaign_id | Affiliate or campaign record linkage. | | affp_assignment_id | Assignment-level coupon linkage. | | affp_user_id | User/payee/affiliate linkage. | | affp_coupon_id | External coupon record linkage. | | affp_subscription_id | Subscription-related coupon linkage. | | affp_bundle_id | Bundle-related coupon linkage. |

---

Security & Permissions

Admin Save Protections

Coupon condition saves include:

• Nonce validation through acb_coupon_nonce.
• Autosave guard.
• shop_coupon post-type guard.
• current_user_can( 'edit_post', $post_id ) capability check.
• Sanitization for role keys, date strings, decimal values, and integer usage limits.

WooCommerce Dependency Guard

The plugin checks for WooCommerce during plugins_loaded. If WooCommerce is not active, the plugin does not initialize and displays an admin error notice.

REST Probe Note

The /ath-coupons/v1/probe endpoint currently uses __return_true as the permission callback. That makes it convenient for development and external validation checks, but production environments should consider whether coupon metadata should be publicly inspectable by anyone who knows a coupon code.

Potential hardening options include:

• Requiring manage_woocommerce for full metadata output.
• Returning only minimal validity status to public users.
• Adding a signed/debug token for Postman or internal QA probes.
• Disabling the route through a constant or filter in production.

---

Implementation Notes From Code Inspection

• The plugin currently targets native WooCommerce shop_coupon records rather than a custom promotion CPT.
• Admin assets are scoped to post.php and post-new.php screens where the post type is shop_coupon.
• acb_allowed_roles excludes guests when any allowed role is configured.
• acb_new_customers_only and acb_first_order_only currently behave the same way: both reject the coupon if completed orders are found for the billing email.
• ACB usage limits are based on completed orders matching the coupon code and billing email, independent of WooCommerce core coupon limits.
• Auto-apply checks only published coupons with acb_auto_apply = 1 unless the query is modified through acb_auto_apply_query_args.
• The saved acb_cart_must_contain_all flag is present in the UI and data model, but deeper custom enforcement of product/category restriction semantics was not visible in the observed code. It appears positioned for future rule expansion or integration with WooCommerce’s native restriction fields.
• The admin JavaScript file is currently reserved for future enhancements and does not add significant active behavior.
• PHP syntax checks passed for all observed plugin PHP files.

---

Developer Extension Examples

Modify the Validation Context

add_filter( 'acb_coupon_validation_context', function ( array $context, WC_Coupon $coupon ) : array {
    $context['custom_channel'] = isset( $_COOKIE['campaign_channel'] )
        ? sanitize_key( wp_unslash( $_COOKIE['campaign_channel'] ) )
        : '';

    return $context;
}, 10, 2 );

Block a Coupon From Auto-Applying

add_filter( 'acb_should_auto_apply_coupon', function ( bool $valid, WC_Coupon $coupon, array $context ) : bool {
    if ( ! $valid ) {
        return false;
    }

    if ( ! empty( $context['coupon_code'] ) && $context['coupon_code'] === 'staff-only' ) {
        return current_user_can( 'manage_woocommerce' );
    }

    return $valid;
}, 10, 3 );

Attach Campaign Context to a Coupon

use Athenian\CouponBuilder\Coupon_API;

Coupon_API::attach_context( $coupon_id, [
    'affp_campaign_id'   => 123,
    'affp_assignment_id' => 456,
    'affp_user_id'       => 789,
] );

Find a Coupon by Campaign Context

use Athenian\CouponBuilder\Coupon_API;

$coupon_id = Coupon_API::find_coupon_for_context( [
    'affp_assignment_id' => 456,
] );

---

Athenian Platform Integration Story

Athenian Coupon Builder fits naturally into the broader Athenian commerce stack as the dedicated promotion and campaign-eligibility layer.

Relevant Athenian Ecosystem Relationships

| Adjacent Module | Relationship | | --- | --- | | Athenian Platform Core | Shared orchestration layer for platform-wide commerce logic and event coordination. | | Pricing Tiers | Complements role/tier pricing by handling coupon-specific promotional overlays. | | Product Subscriptions & Bundles | Coupon context keys include subscription and bundle linkage fields. | | Store Credits & Rewards | Can coexist with stored-value and loyalty systems as a separate coupon eligibility layer. | | OwlPay / Affiliate Systems | affp_* context keys suggest affiliate or assignment-driven coupon campaigns. | | Custom Cart Builder | Auto-apply and coupon validation can support guided buying or account-based cart flows. | | Quote Builder | Coupon rules may eventually support quote approval incentives or campaign-linked quote discounts. |

---