Athenian Supplier & Cost-of-Goods Tracking for WooCommerce

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. Create Suppliers

Admins create supplier records under the WooCommerce supplier menu. Supplier records support title, notes, email, phone, and website fields.

2. Define Raw Material Costing

Raw materials can be created as WooCommerce products or variations. Admins assign purchase cost, units per purchase, and unit label. The plugin calculates a derived unit cost from those values.

3. Assign Costs to Finished Products

Finished products can either have their own purchase-unit cost or be built from raw material components. Components define which product or variation is consumed and how much is used per finished unit.

4. Override Variation Costs as Needed

Variations can inherit parent product settings or override individual COGS fields. This keeps large product families manageable while still allowing accurate cost detail where variations differ.

5. Review and Edit in the Manager Screen

The Supplier & COGS Manager allows admins to search, filter, edit, and save costing data without opening every product manually.

6. Include Asset Consumables When Available

If Athenian Asset Management is configured, product or variation asset usage can contribute additional consumable cost to the COGS estimate.

---

Technical Overview

Plugin Bootstrap

Main file:

athenian-supplier-cogs-tracking.php

The plugin defines constants for version, directory, and URL, loads supporting classes, registers activation/deactivation hooks, and initializes key admin services.

Loaded classes:

includes/class-ath-cogs-utils.php
includes/class-ath-cogs-cpt-supplier.php
includes/class-ath-cogs-product-meta.php
includes/class-ath-cogs-admin.php
includes/class-ath-cogs-asset-integration.php

Initialization Hooks

The plugin initializes through WordPress and WooCommerce admin hooks:

init
admin_init
admin_enqueue_scripts
woocommerce_product_data_tabs
woocommerce_product_data_panels
woocommerce_admin_process_product_object
woocommerce_product_after_variable_attributes
woocommerce_save_product_variation
save_post_product
save_post_product_variation

The plugin is admin-focused and only loads its interface assets for relevant product, manager, and eligible asset editor screens.

---

Data Model

Supplier CPT

Post Type: ath_supplier

Supplier meta fields:

_ath_supplier_email
_ath_supplier_phone
_ath_supplier_site

Product and Variation Meta

_ath_cogs_supplier_id
_ath_cogs_purchase_cost
_ath_cogs_purchase_units
_ath_cogs_purchase_unit_label
_ath_cogs_components_json

AAM / Asset Usage Meta

Primary AAM-owned product or variation asset usage key:

_aam_asset_usage_json

Legacy fallback key:

_ath_cogs_asset_usage_json

Asset consumable definition keys:

_aam_cogs_measure_unit
_aam_cogs_consumables_json
_ath_cogs_asset_measure_unit
_ath_cogs_asset_consumables_json

The plugin writes both AAM-oriented and legacy COGS-oriented asset consumable keys in the fallback asset metabox save routine for compatibility.

---

Cost Calculation Models

Purchase Unit Cost

unit_cost = purchase_cost / purchase_units

Used for raw materials, standalone products, and variation overrides.

Component Cost

component_cogs = Σ(raw_unit_cost × quantity_consumed_per_finished_unit)

Each component row supports:

{
  "product_id": 123,
  "variation_id": 0,
  "qty": 1,
  "note": "Example raw material"
}

Asset Consumable Cost

asset_cost = Σ(unit_cost(consumable) × measure_qty × per_measure × share_pct)

Asset consumable rows support:

{
  "product_id": 123,
  "variation_id": 0,
  "per_measure": 0.25,
  "share_pct": 16.67,
  "note": "Cyan ink usage"
}

Product or variation asset usage rows support:

{
  "asset_id": 456,
  "measure_qty": 12.5,
  "share_pct": 0,
  "consumables": []
}

Computed Preview

The manager UI exposes computed values for:

Unit Cost
Components COGS
Asset COGS
Total COGS
Batch Qty Preview

The current backend ajax_get_cogs response calculates component and asset cost, and returns a total preview. In the reviewed version, the total_cogs response is currently based on component and asset cost, while direct unit cost is separately returned as unit_cost.

---

AJAX Endpoints

All AJAX endpoints require WooCommerce management capability and a verified nonce using the plugin nonce action.

| Action | Purpose | |---|---| | ath_cogs_search_products | Search products and variations by name/SKU and optional supplier/type filters. | | ath_cogs_get_cogs | Load COGS detail for a product or variation, including inherited values and computed costs. | | ath_cogs_save_cogs | Save supplier, purchase unit fields, component rows, inheritance flags, and asset usage data. | | ath_cogs_list_suppliers | Return supplier options for manager dropdowns. | | ath_cogs_list_assets | Return available AAM assets when the aam_asset post type exists. | | ath_cogs_calc_components_cost | Calculate total component cost from a submitted component JSON payload. |

---

Permissions and Security

The plugin is designed for WooCommerce administrative users.

Security controls include:

• manage_woocommerce checks for manager access.
• current_user_can('edit_post', $id) checks before saving target post data.
• AJAX nonce validation through the ath_cogs_admin nonce action.
• Sanitization of supplier contact fields.
• Numeric sanitization for cost, unit, and quantity values.
• Field-by-field normalization of component JSON arrays.
• Defensive JSON repair instead of unsafe whole-blob sanitization.
• Admin-only asset enqueueing on supported screens.
• Escaped output for admin fields and rendered UI values.

---

Implementation Notes From Review

• The plugin performs clean PHP syntax validation across all PHP files in the reviewed ZIP.
• The product editor adds a Suppliers & COGS WooCommerce data tab.
• The manager screen is registered under WooCommerce as Supplier & COGS.
• The supplier CPT is private on the frontend but visible in the WordPress admin UI.
• Variation save handling includes both WooCommerce variation hooks and post-save repair hooks.
• Component JSON handling is intentionally defensive because production notes may include quotes or inch marks.
• Asset usage is treated as AAM-owned when newer AAM functionality is detected.
• The plugin currently focuses on admin-side data management and computed previews, not frontend display.

---