Athenian Custom Cart Builder

Developer starting point

This page documents the reviewed Custom Cart Builder source baseline and a separate representative tiered fleet deployment observation. It does not claim that a cart, checkout, payment, order, vendor action, or fulfillment effect has been exercised.

Customer-Facing Workflow

1. The customer visits a page containing [custom_cart_builder].
2. If logged out, the customer is prompted to log in.
3. If logged in, WooCommerce cart/session/customer objects are initialized.
4. Customer profile, billing, and shipping cards render from WooCommerce customer data.
5. Previous purchases render from recent WooCommerce orders.
6. The customer searches products or adds previous purchases.
7. AJAX cart operations update the cart and return a fresh snapshot.
8. Cart rows expose quantity, removal, add-ons, vendor options, subscription choices, and FastPass controls where applicable.
9. WooCommerce checkout review, shipping methods, coupons, credits, and payment methods render inside the portal.
10. WooCommerce processes the final order through normal checkout behavior.

---

Technical Architecture

Bootstrap File

athenian-custom-cart-builder.php defines plugin constants, declares WooCommerce HPOS compatibility, checks for WooCommerce availability, and loads the plugin modules.

Loaded modules include:

• includes/shortcode.php
• includes/assets.php
• includes/ajax-cart.php
• includes/ajax-products.php
• includes/ajax-profile.php
• includes/ajax-previous.php
• includes/checkout-bridge.php
• includes/addons-bridge.php

The cart AJAX controller also loads the optional cart-line bridge modules:

• includes/fastpass-bridge.php
• includes/subscriptions-bridge.php
• includes/vendor-bridge.php

Shortcode Layer

File: includes/shortcode.php Shortcode: [custom_cart_builder] Render function: accb_render_custom_cart_builder()

The shortcode is responsible for:

• Requiring login.
• Loading WooCommerce cart/session context.
• Pulling current user and customer data.
• Rendering customer, billing, and shipping cards.
• Rendering previous purchases.
• Rendering search and cart containers.
• Rendering the checkout form and WooCommerce checkout hooks.
• Synchronizing visible order notes to WooCommerce order_comments.

Supported shortcode attributes include:

| Attribute | Purpose | Default | | --- | --- | --- | | prev_limit | Maximum number of previous purchase products shown in the initial server-rendered list. | 12 | | prev_days | Optional date window for previous purchases. 0 means no date limit. | 0 |

Example:

[custom_cart_builder prev_limit="16" prev_days="180"]

Asset Layer

File: includes/assets.php Class: ACCB_Assets

The asset manager registers but does not globally enqueue frontend assets. Assets are enqueued only when the portal shortcode renders.

Registered scripts include:

• assets/js/accb-spinner.js
• assets/js/custom-cart-builder.js

Registered styles include:

• assets/css/accb-spinner.css
• assets/css/accb-base.css
• assets/css/accb-cart.css
• assets/css/accb-checkout.css
• assets/css/accb-customer.css
• assets/css/accb-search.css
• assets/css/accb-previous.css
• assets/css/accb-woo-overrides.css

Localized JavaScript object:

ACCB_PORTAL = {
  ajax_url: ".../wp-admin/admin-ajax.php",
  nonces: {
    search: "...",
    cart: "...",
    previous: "...",
    profile: "..."
  },
  debug: {
    plugin_version: "1.0.0",
    request_uri: "...",
    ts: 1234567890
  }
}

AJAX Cart Controller

File: includes/ajax-cart.php Class: ACB_Ajax_Cart in concept, implemented as ACCB_Ajax_Cart AJAX action: accb_cart_ops

Registered hooks:

wp_ajax_accb_cart_ops
wp_ajax_nopriv_accb_cart_ops

Even though the action is registered for non-authenticated users, the primary shortcode portal itself requires login.

The controller bootstraps WooCommerce runtime inside admin-ajax.php by loading cart, session, customer, and cart contents from session. After operations, it calculates totals, persists the cart session, sets cart cookies, and returns a JSON snapshot.

Product Search Controller

File: includes/ajax-products.php AJAX action: accb_search_products

Registered hooks:

wp_ajax_accb_search_products
wp_ajax_nopriv_accb_search_products

Search parameters:

| Parameter | Description | | --- | --- | | term | Search phrase. Requires at least 2 characters. | | limit | Maximum result count. Capped at 50. | | security | Search nonce. Also accepts the cart nonce for backward compatibility. |

Search response includes:

• id
• name
• sku
• thumb
• breadcrumbs
• price_html
• stock_html
• in_stock
• permalink

Previous Purchases Controller

File: includes/ajax-previous.php AJAX actions: accb_previous_orders, accb_previous_purchases

Registered hooks:

wp_ajax_accb_previous_orders
wp_ajax_nopriv_accb_previous_orders
wp_ajax_accb_previous_purchases

The previous-purchase endpoint:

• Requires a valid previous-orders or cart nonce.
• Requires a logged-in user.
• Searches paid WooCommerce orders by customer ID.
• Falls back to billing email when no customer ID orders are found.
• Returns unique product rows with thumbnail, product name, SKU, price, last purchased date, and add-to-cart action.

Profile Controller

File: includes/ajax-profile.php Class: ACCB_Ajax_Profile AJAX action: accb_profile

Registered hooks:

wp_ajax_accb_profile
wp_ajax_nopriv_accb_profile

The profile controller:

• Requires a valid accb_profile_ops nonce.
• Requires WooCommerce and a logged-in user.
• Saves billing fields to the WooCommerce customer.
• Saves shipping fields to the WooCommerce customer.
• Updates the WordPress user email when billing email changes.
• Stores the portal order note in WooCommerce session under accb_order_note.
• Copies the session note onto the WooCommerce order during woocommerce_checkout_create_order.

Checkout Bridge

File: includes/checkout-bridge.php Class: ACCB_Checkout_Bridge

> Source reference excerpt truncated; use the linked technical reference and repository baseline for the full implementation context.

Data Model and Persistence

WordPress User Data

The profile handler may update the WordPress user's email address when a valid billing email is submitted.

WooCommerce Customer Data

Billing fields saved through the portal:

• billing_first_name
• billing_last_name
• billing_company
• billing_phone
• billing_email
• billing_address_1
• billing_address_2
• billing_city
• billing_state
• billing_postcode
• billing_country

Shipping fields saved through the portal:

• shipping_first_name
• shipping_last_name
• shipping_company
• shipping_phone
• shipping_address_1
• shipping_address_2
• shipping_city
• shipping_state
• shipping_postcode
• shipping_country

WooCommerce Session Data

| Session key | Purpose | | --- | --- | | accb_order_note | Temporary order note saved from the portal and transferred to the order during checkout. |

Cart Item Data

| Cart item key | Purpose | | --- | --- | | accb_addons_meta | ACCB-owned add-on metadata. | | ath_addons | Compatibility mirror for Athenian Product Add-ons. | | accb_fastpass | ACCB-owned FastPass selection state. | | afp_fastpass | Compatibility mirror for FastPass-style plugins. | | accb_subscription | ACCB-owned subscription selection state. | | aps_subscription | Compatibility mirror for Athenian subscription logic. | | apc_vendor_id | Selected vendor ID for a cart line. |

Product Metadata

| Meta key | Purpose | | --- | --- | | _apc_vendor_offers | Vendor offer data consumed by the vendor bridge. | | _afp_fastpass_enabled | Enables FastPass UI for a product. | | _afp_fastpass_label | FastPass label. | | _afp_fastpass_description | FastPass description. | | _afp_fastpass_fee_mode | FastPass fee mode. | | _afp_fastpass_fee_amount | FastPass fee amount. | | _aps_enabled | Enables subscription UI for a product. | | _aps_interval | Subscription interval. | | _aps_interval_unit | Subscription interval unit. | | _aps_anchor_date | Optional subscription anchor date. |

---

Integration Points

WooCommerce

The plugin relies on WooCommerce for:

• Product data.
• Product variations.
• Cart sessions.
• Customer records.
• Checkout rendering.
• Payment gateways.
• Shipping methods.
• Coupons.
• Cart fragments.
• Order creation.
• HPOS-compatible order retrieval.

Athenian Platform Core

The vendor bridge is designed to work with Athenian Platform Core vendor offer metadata and price delegation. If the Platform Core PriceDelegate class exists, the cart builder avoids taking over price authority and allows the platform to resolve vendor-aware pricing.

Athenian Product Add-ons

The add-ons bridge can use the shared Athenian Product Add-ons provider contract:

ath_addons/render_fields_html
ath_addons/apply_posted_meta

It also exposes ACCB-native hooks for alternate add-on providers.

Athenian Subscriptions

The subscription bridge stores cart item state in both ACCB and APS-compatible keys, allowing downstream subscription tooling to interpret selected recurring purchase options.

FastPass / Priority Service Logic

The FastPass bridge stores selected upgrade state and emits accb/fastpass/applied, giving external logic an opportunity to apply fees, adjust service priority, or trigger operational handling.

Store Credit, Loyalty, and Credits Panel

The checkout layout includes this action hook:

do_action( 'accb_checkout_credits_panel', $checkout );

This gives store credit, loyalty, or rewards integrations a designated area inside the portal checkout column.

---

Hooks, Filters, and Extension Surface

Add-ons Hooks

apply_filters( 'accb/render_addons_for_cart_item', $html, $cart_item_key, $cart_item );
do_action( 'accb/apply_addons_meta_to_cart_item', $cart_item_key, $addons_meta_for_item );

Fallback Athenian add-ons hooks:

apply_filters( 'ath_addons/render_fields_html', $html, $product, $cart_item, $cart_item_key, 'accb', $saved_values );
do_action( 'ath_addons/apply_posted_meta', $cart_item_key, $addons_meta_for_item, $cart_item, 'accb' );

FastPass Hooks

apply_filters( 'accb/fastpass/is_eligible', $eligible, $product, $cart_item, $cart_item_key, $context );
apply_filters( 'accb/fastpass/render_extra', $extra, $product, $cart_item, $cart_item_key, $context, $selected, $config );
do_action( 'accb/fastpass/applied', $cart_item_key, $normalized_payload, $context );

Vendor Hooks

apply_filters( 'apc_store_vendor_name', $store_vendor_name );
do_action( 'accb/vendor_applied', $cart_item_key, $vendor_id, $matched_offer, $context );

Cart Snapshot Debug Filter

apply_filters( 'accb/cart_snapshot_debug', $debug );

When enabled, cart snapshots include additional diagnostic data for add-ons, vendor, subscription, and FastPass rendering.

Checkout Credits Hook

do_action( 'accb_checkout_credits_panel', $checkout );

---

Security and Reliability Notes

• AJAX requests are nonce-protected by operation type.
• Profile saves require both a valid nonce and a logged-in user.
• Search and cart endpoints sanitize request parameters before use.
• Cart operations explicitly bootstrap WooCommerce runtime in AJAX context.
• Cart totals are recalculated after cart changes.
• Cart session and cart cookies are persisted after AJAX operations.
• Product search limits are capped to prevent excessive query sizes.
• Add-on metadata is sanitized recursively.
• Vendor IDs, product IDs, quantities, and limits are cast to integers.
• Checkout bridge uses public WooCommerce APIs to reduce version compatibility risk.

---

Implementation Notes

Recommended Page Setup

Create a logged-in customer portal page and place the shortcode in the content area:

[custom_cart_builder]

Optional previous purchase tuning:

[custom_cart_builder prev_limit="20" prev_days="365"]

Required Dependencies

• WordPress 6.2 or newer.
• PHP 8.0 or newer.
• WooCommerce active.

Optional Ecosystem Dependencies

• Athenian Platform Core for vendor-aware pricing delegation.
• Athenian Product Add-ons for configurable cart-line fields.
• Athenian subscription tooling for recurring purchase handling.
• FastPass-style service upgrade tooling.
• Store credit, gift card, loyalty, or rewards integrations.

Theme Integration

The portal is designed to be self-contained and scoped, but it will look best when the active site theme exposes compatible surface, text, border, and accent tokens.

---

Known Implementation Considerations

• The shortcode experience is intentionally login-gated, so anonymous shopping use cases should continue to use the normal WooCommerce storefront unless the portal is extended.
• The plugin renders coupon and gift card interface regions, but production behavior depends on WooCommerce and any installed coupon, gift card, or credit integrations.
• The profile AJAX handler exists for saving billing, shipping, and order-note data; frontend save-button wiring should be verified in the deployed UI because the current JavaScript focuses heavily on cart, search, and line-option behavior.
• Vendor pricing can be handled directly by the bridge only when Athenian Platform Core's price delegate is not active. In full platform deployments, pricing should be treated as platform-owned.
• Product variations are searched and can be added by variation ID, while variable parent products are intentionally excluded from direct search results.

---

Deployment evidence\n\nObserved deployment version: 1.0.1-tiered (Representative Athenian Spa/NailTechDatabase tiered deployment capture). The captured deployment archive custom-cart-builder-1.0.1-tiered.tar.gz has SHA-256 c2f0c8d8a4220a52abff5fa17cb572458bd493d538a374998e1d3cf4c07dfba0. The deployed tiered tree is a separate fleet release from the reviewed 1.4.31 source baseline. GitHub master resolves to the recorded 1.0.1-tiered repository state, so the two identities should remain explicit until a product decision selects the canonical release line.

Deployment and source parity

Observed deployment version: 1.0.1-tiered (Representative Athenian Spa/NailTechDatabase tiered deployment capture). The captured deployment archive custom-cart-builder-1.0.1-tiered.tar.gz has SHA-256 c2f0c8d8a4220a52abff5fa17cb572458bd493d538a374998e1d3cf4c07dfba0. The deployed archive and GitHub v1.0.1-tiered each contain 35 normalized files. All 35 common files match after line-ending normalization; the 23 raw byte differences are line-ending normalization only. The 1.4.31 source snapshot remains the reviewed technical reference. The captured tiered deployment is now represented by the canonical GitHub v1.0.1-tiered release identity, with normalized source parity established.

Live fleet review — 2026-10-07

The current Athenian Brands deployment is active at 1.0.0 with installed main-file SHA-256 b86d4193b45532e6c8749ef10983b166966ce4f48a828723a881304e02e9c8a5. The documented canonical tiered release remains v1.0.1-tiered at commit ae47bbb41957305f97231ccf73c3d3aff64f6a2e, with normalized full-tree parity already recorded for that release. Athenian Spa is active on 1.0.1-tiered; NailTechDatabase and ThixStrip retain inactive site copies.

Read-only runtime inspection on Athenian Brands confirmed the [custom_cart_builder] shortcode, the ACCB_Ajax_Cart controller, cart/search/profile/previous-purchase AJAX registrations, and the accb_settings option. No cart item, customer, checkout, payment, order, vendor, or fulfillment state was changed or exercised.

This is a documented site-version lag, not an authorization to promote the tiered release. Preserve the current cart contract and run a separately authenticated, non-submitting UI canary before making a version decision.