Athenian Pricing Tiers

Developer starting point

This page documents the reviewed Pricing Tiers source baseline and the observed 0.5.4/0.5.5 fleet versions. It does not claim that a live tier rule, cart total, checkout total, or customer-specific price has been exercised.

Technical & Marketing Brief

Athenian Pricing Tiers is a WooCommerce quantity-pricing module for defining, displaying, importing, exporting, and integrating tiered pricing rules across simple products, variable products, variations, storefront product pages, cart upsell messaging, and broader Athenian Platform pricing workflows.

The plugin is designed to make bulk pricing operationally manageable. Merchants can author fixed unit-price or percentage-discount tiers inside WooCommerce, shoppers can see clean bulk-pricing cards on product pages, and platform components can consume normalized tier data through familiar WooCommerce/Tiered Pricing Table-style metadata and filters.

---

Primary Workflow Surfaces

| Workflow Surface | Operational Purpose | | --- | --- | | Product editor | Configure tier mode, minimum quantity, and tier rows for simple products and variable product parents. | | Variation editor | Override or define tiers at the individual variation level. | | Storefront product page | Render bulk-pricing cards before the add-to-cart form or late in the product summary as a fallback. | | Quantity input bridge | Allow shoppers to click tier cards and automatically set the product quantity to the tier threshold. | | Cart Blocks | Display next-tier upsell pills in WooCommerce Blocks cart rows when APC tier extension data is available. | | WooCommerce CSV | Export and import tier rules using dedicated product CSV columns. | | Compatibility filters | Publish normalized rules through the tiered_pricing_table_rules filter. | | Platform pricing hooks | Provide hooks such as apt_tier_unit_price, apt_tier_blocks, apt/product_min_qty, and ath/apc/role_discount_for_price for broader pricing logic. |

---

Admin Workflow

1. Open a WooCommerce product in the WordPress admin.
2. For a simple product, configure tiers in the pricing area of the General product tab.
3. For a variable product, use the added Tiered Pricing product data panel for parent-level rules.
4. For variation-specific pricing, expand a variation and configure that variation's own tier mode, minimum quantity, and tier rows.
5. Choose the pricing mode:

• fixed for final per-unit prices.
• percentage for discount percentages.

1. Add quantity bands with qty_from, optional qty_to, and price/discount values.
2. Leave qty_to blank for an open-ended tier.
3. Save the product to persist canonical tier metadata.

---

Storefront Workflow

On single product pages, the plugin attempts to render a customer-facing bulk-pricing block.

The frontend renderer:

1. Confirms the page is a WooCommerce single product.
2. Skips grouped and external products.
3. Reads normalized rules through tiered_pricing_table_rules.
4. For variable products without parent rules, attempts to find a matching default variation or the first child variation with tier data.
5. Falls back to legacy _fixed_price_rules metadata when the filter does not return data.
6. Applies the apt_tier_unit_price filter so PriceDelegate or other integrations can adjust the effective unit price.
7. Calculates discount labels against the product's regular price when possible.
8. Renders clickable tier cards with range labels, unit prices, and savings badges.
9. Uses frontend JavaScript to set the quantity input when a shopper clicks a tier card.

---

Cart Blocks Upsell Workflow

The package includes assets/js/apc-cart-tier-upsells.js, which is built for WooCommerce Blocks cart pages.

It reads the WooCommerce Blocks cart store through wp.data, inspects cart item extension payloads, and looks for Athenian Platform Core-style extension data under keys such as:

• extensions.apc
• extensions.APC
• extensions.AthAPC

When tier data or next-tier data is available, it renders a cart-line upsell pill such as:

> Add 3 more to unlock $12.50 per unit.

The script is designed to account for server-provided final unit pricing when available, while also supporting local fallback calculations involving:

• next base tier price
• role-discount factor
• percentage add-ons
• flat add-ons
• vendor display name
• add-on signature changes
• WooCommerce Blocks cart line totals

This makes the cart UI a merchandising layer rather than merely a static product-page display.

---

Technical Architecture

Active Bootstrap

The root plugin file is athenian-pricing-tiers.php.

The reviewed plugin header reports:

| Header | Value | | --- | --- | | Plugin Name | Athenian Pricing Tiers | | Description | Lightweight tiered pricing storage & UI compatible with Tiered Pricing Table meta keys. | | Version | 0.5.4 | | Author | Scott Mays / Athenian Brands | | Namespace | Athenian\PricingTiers |

The root file defines:

• APT_VERSION
• APT_DEBUG
• ath_pricing_expose_rest_config()
• Plugin singleton class

The root file directly requires:

• includes/class-frontend-ui.php
• includes/class-woo-csv.php

The inline Plugin class boots WooCommerce-aware product editor behavior, tier rule storage, filters, frontend asset enqueueing, and CSV support.

Package Structure

| Path | Purpose | | --- | --- | | athenian-pricing-tiers.php | Main plugin bootstrap and active product/variation tier logic. | | includes/class-frontend-ui.php | Product-page tier block renderer and cart asset enqueueing. | | includes/class-woo-csv.php | WooCommerce product CSV export/import support for tier fields. | | includes/class-admin-ui.php | Alternate/legacy admin meta-box style tier editor component. | | includes/class-plugin.php | Alternate modular plugin bootstrap that references Admin UI, Rules Store, Role Discounts, and Frontend UI. | | includes/class-rules-store.php | Standalone compatibility filter for stored tier rules. | | includes/class-role-discounts.php | Role discount settings, filter integration, and [role_discount_display] shortcode. | | includes/class-rest-role-discount-endpoint.php | REST/AJAX role-discount probe endpoint class. | | assets/js/admin.js | Admin tier editor row handling, mode toggles, summaries, sorting, add/remove controls. | | assets/css/admin.css | Admin editor styling. | | assets/js/frontend-tiers.js | Product-page tier card click and active-state behavior. | | assets/css/frontend-tiers.css | Storefront bulk-pricing block styling. | | assets/js/apc-cart-tier-upsells.js | WooCommerce Blocks cart tier upsell pill rendering. | | assets/css/apc-cart-tier-upsells.css | Cart upsell styling. | | athenian-pricing-tiers-marketing-document.md | Source marketing draft included in the ZIP. | | docs/athenian-platform-marketing.md | Platform-level marketing context. | | docs/athenian-platform-technical.md | Platform-level technical scan/context. |

---

Important Implementation Note

The ZIP contains both an active inline bootstrap in athenian-pricing-tiers.php and several modular class files in includes/.

In the reviewed package, the root plugin file directly requires only:

• includes/class-frontend-ui.php
• includes/class-woo-csv.php

The following files are present but do not appear to be directly required by the active root file as reviewed:

• includes/class-admin-ui.php
• includes/class-plugin.php
• includes/class-rules-store.php
• includes/class-role-discounts.php
• includes/class-rest-role-discount-endpoint.php

That means the role-discount submenu, REST endpoint, AJAX endpoint, alternate admin UI, and standalone rules-store class should be treated as bundled or future-facing components unless another loader/autoloader requires them in the deployed environment. Before marketing those components as active production behavior, confirm whether the deployed copy wires those classes into the runtime.

The package passed a PHP syntax check across the root and included PHP files during review.

---

Data Model

Canonical Active Meta Keys

The active root plugin uses Tiered Pricing Table-compatible meta keys:

| Meta Key | Purpose | Expected Shape | | --- | --- | --- | | _tiered_price_rules_type | Active pricing mode. | fixed or percentage | | _tiered_price_minimum_qty | Minimum quantity that can enter tiered pricing. | Integer, minimum 1 | | _fixed_price_rules | Fixed unit-price tier rows. | Array of rows with qty_from, qty_to, price | | _percentage_price_rules | Percentage discount tier rows. | Array of rows with qty_from, qty_to, price |

Tier Row Shape

Each rule row is normalized toward this structure:

{
  "qty_from": 10,
  "qty_to": 24,
  "price": 19.99
}

For open-ended tiers, the active storage normalizes blank or legacy 0 values to an empty value for admin storage, then outputs null through the compatibility filter where appropriate:

{
  "qty_from": 25,
  "qty_to": null,
  "price": 17.50
}

Role Discount Option

The bundled role-discount class uses this option name:

apt_role_discounts

Expected shape:

{
  "wholesale_customer": {
    "percent": 10
  },
  "distributor": {
    "percent": 20
  }
}

As noted above, this class is present in the package but should be confirmed as loaded in the active runtime before relying on the settings UI or shortcode.

Legacy / Alternate Meta Keys

The included alternate Admin_UI and Rules_Store classes refer to:

| Meta Key | Purpose | | --- | --- | | _tiered_price_fixed_price | Legacy or alternate fixed-tier storage. | | _apt_tiered_price_rules | Athenian-specific mirrored tier rows. |

These appear in the modular include files rather than the active inline bootstrap.

---

WooCommerce Integration Points

Product Editor Hooks

The active root plugin uses:

| Hook | Purpose | | --- | --- | | woocommerce_product_data_tabs | Adds the Tiered Pricing tab for variable products. | | woocommerce_product_data_panels | Renders parent variable-product tier panel. | | woocommerce_product_options_pricing | Renders tier controls for simple products in the pricing section. | | woocommerce_variation_options_pricing | Renders tier controls inside variation pricing panels. | | woocommerce_admin_process_product_object | Saves product-level tier metadata. | | woocommerce_save_product_variation | Saves variation-level tier metadata. | | admin_enqueue_scripts | Loads admin tier editor assets on product edit screens. |

Frontend Hooks

| Hook | Purpose | | --- | --- | | wp_enqueue_scripts | Loads frontend tier assets and cart upsell assets when applicable. | | woocommerce_before_add_to_cart_form | Primary tier-block placement before the add-to-cart form. | | woocommerce_single_product_summary | Fallback tier-block placement late in the summary. |

CSV Hooks

| Hook | Purpose | | --- | --- | | woocommerce_product_export_column_names | Adds export column labels. | | woocommerce_product_export_product_default_columns | Adds tier fields to default export columns. | | woocommerce_product_export_product_column_apt_tiered_price_type | Exports active tier mode. | | woocommerce_product_export_product_column_apt_tiered_price_min_qty | Exports minimum quantity. | | woocommerce_product_export_product_column_apt_fixed_price_rules_json | Exports fixed tier rows as JSON. | | woocommerce_product_export_product_column_apt_percentage_price_rules_json | Exports percentage tier rows as JSON. | | woocommerce_csv_product_import_mapping_options | Adds importer mapping options. | | woocommerce_csv_product_import_mapping_default_columns | Auto-maps friendly and meta-style column names. | | woocommerce_product_importer_parsed_data | Stashes parsed tier payloads during import. | | woocommerce_product_import_inserted_product_object | Writes tier metadata after WooCommerce creates/updates the product. |

---

Filters and Extension Points

| Filter | Purpose | | --- | --- | | tiered_pricing_table_rules | Publishes normalized fixed-price tiers in a Tiered Pricing Table-compatible format. | | apt/product_min_qty | Allows consumers to read/override minimum product quantity from tier metadata. | | apt_tier_unit_price | Lets PriceDelegate or other integrations adjust the effective unit price before frontend rendering. | | apt_tier_blocks | Allows final manipulation of frontend tier card data before output. | | ath/apc/role_discount_for_price | Bundled role-discount component can expose role discount percentages to APC/PriceDelegate-style pricing logic. |

---

Deployment evidence\n\nObserved deployment version: 0.5.4 and 0.5.5 (Representative fleet deployment inventory). The captured deployment archive pricing-tiers-0.5.5.tar.gz has SHA-256 f50d5e58f50f0be3679445e75ee4b51d098118852fd2ded00665332884f397d9. Six observed sites run 0.5.4 and three observed sites run 0.5.5. GitHub exposes the v0.5.5 release tag, while this page retains the reviewed 0.5.4 source baseline until the fleet promotion decision is made.

Deployment and source parity

Observed deployment version: 0.5.4 and 0.5.5 (Representative fleet deployment inventory). The captured deployment archive pricing-tiers-0.5.5.tar.gz has SHA-256 f50d5e58f50f0be3679445e75ee4b51d098118852fd2ded00665332884f397d9. The deployed 0.5.5 archive and GitHub v0.5.5 each contain 15 files and match byte-for-byte across all 15 files. Six observed sites remain on 0.5.4 and three observed sites run 0.5.5. The 0.5.4 source snapshot remains the reviewed implementation reference, while the latest deployed 0.5.5 release is now the canonical repository identity for current-release documentation. Site-specific version differences remain explicit.