Athenian Tax Exemption for WooCommerce

Developer starting point

This baseline documents tax-exemption code and WooCommerce hooks. It does not claim a jurisdiction-specific tax result or production checkout outcome.

Admin Workflow

Setup Workflow

1. Install and activate the plugin.
2. Confirm WooCommerce is active.
3. Visit WooCommerce → Tax Exemption.
4. Confirm the exempt role slug, usually tax_exempt.
5. Choose eligibility methods: role, user meta, certificates, or a combination.
6. Choose enforcement mode: recommended vat_exempt, or zero_rate if the store requires tax-class forcing.
7. Configure REST override behavior only if needed for integrations or headless checkout.
8. Enable logging/debugging during rollout, then reduce logging if not needed.

Customer Approval Workflow

1. Open the customer's WordPress user profile.
2. Assign the configured exempt role and/or enable the tax-exempt user meta checkbox.
3. Upload or select the customer's exemption certificate, if certificate tracking is enabled.
4. Enter the certificate expiration date, if applicable.
5. Verify the certificate status pill.
6. Test the customer in cart/checkout or run a debug probe.

Order Exception Workflow

1. Open the WooCommerce order edit screen.
2. Use the Tax Exemption metabox.
3. Check Treat this order as tax-exempt.
4. Save the order.
5. Recalculate order totals if needed based on the store's order editing workflow.
6. Confirm the order list shows the tax-exempt indicator.

Integration Workflow

1. Enable REST header override.
2. Configure the trusted header name.
3. Choose eligible_only unless the integration is fully trusted and secured.
4. Send the configured header with a truthy value from the integration.
5. Ensure the WooCommerce session/customer context is established where required.
6. Confirm exemption behavior in cart/checkout totals.

---

Technical Architecture

File Structure

athenian-tax-exemption-for-woocommerce.php
assets/
  admin.css
  admin.js
docs/
  atew-marketing-document.md
includes/
  class-atew-admin.php
  class-atew-determiner.php
  class-atew-order-admin.php
  class-atew-plugin.php
  class-atew-settings.php

Core Classes

| Class | File | Responsibility | |---|---|---| | ATEW\Plugin | includes/class-atew-plugin.php | Main runtime bootstrap, WooCommerce hooks, REST override capture, tax enforcement, multisite role sync. | | ATEW\Settings | includes/class-atew-settings.php | Default settings, option retrieval, boolean helper. | | ATEW\Determiner | includes/class-atew-determiner.php | Central exemption and eligibility decision engine. | | ATEW\Admin | includes/class-atew-admin.php | WooCommerce settings page, settings sanitization, assets, user profile fields, debug AJAX. | | ATEW\Order_Admin | includes/class-atew-order-admin.php | Order metabox, order meta persistence, legacy order list column. |

Bootstrap Flow

The main plugin file defines constants, loads class files, and starts the plugin on plugins_loaded priority 5:

add_action('plugins_loaded', function(){
    \ATEW\Plugin::instance();
}, 5);

The main plugin instance then:

1. Registers activation behavior.
2. Captures configured REST headers on init priority 2.
3. Boots WooCommerce-specific integrations after plugins are loaded.
4. Initializes admin and order-admin classes in the dashboard.

WooCommerce Hook Map

| Hook | Type | Purpose | |---|---|---| | woocommerce_customer_is_vat_exempt | Filter | Returns true for exempt customers. | | woocommerce_init | Action | Proactively sets the WooCommerce customer VAT-exempt flag. | | woocommerce_product_get_tax_class | Filter | Forces product tax class in zero-rate mode. | | woocommerce_product_variation_get_tax_class | Filter | Forces variation tax class in zero-rate mode. | | woocommerce_fee_tax_class | Filter | Forces fee tax class in zero-rate mode. | | woocommerce_shipping_rate_tax_status | Filter | Disables shipping tax status for exempt customers. | | woocommerce_shipping_rate_tax_class | Filter | Clears or zero-rates shipping tax class for exempt customers. | | woocommerce_cart_calculate_fees | Action | Marks fees as non-taxable and clears fee tax data. | | woocommerce_package_rates | Filter | Clears tax arrays on shipping rate objects. | | woocommerce_cart_get_taxes | Filter | Clears cart taxes. | | woocommerce_cart_tax_totals | Filter | Clears cart tax totals display data. | | woocommerce_cart_get_shipping_taxes | Filter | Clears shipping taxes. | | woocommerce_cart_shipping_taxes | Filter | Clears shipping taxes. | | woocommerce_cart_totals_get_shipping_taxes | Filter | Clears shipping tax totals arrays. | | woocommerce_cart_totals_get_shipping_tax | Filter | Returns zero shipping tax total. | | woocommerce_after_calculate_totals | Action | Final post-calculation cleanup of cart/shipping tax properties. |

Admin Hook Map

| Hook | Type | Purpose | |---|---|---| | admin_menu | Action | Adds the WooCommerce Tax Exemption submenu. | | admin_init | Action | Registers settings and fields. | | admin_enqueue_scripts | Action | Loads admin CSS/JS and media picker support. | | wp_ajax_atew_debug_probe | Action | Returns current-user exemption diagnostic data. | | show_user_profile | Action | Displays user profile exemption fields. | | edit_user_profile | Action | Displays exemption fields when editing another user. | | personal_options_update | Action | Saves current-user profile exemption fields. | | edit_user_profile_update | Action | Saves edited-user profile exemption fields. | | add_meta_boxes | Action | Adds the order tax exemption metabox. | | save_post_shop_order | Action | Saves order tax exemption meta. | | woocommerce_process_shop_order_meta | Action | Saves order tax exemption meta through legacy WooCommerce order processing. | | manage_edit-shop_order_columns | Filter | Adds the order list Tax Exempt column. | | manage_shop_order_posts_custom_column | Action | Renders the order list status indicator. |

---

Data Model and Settings

Option Key

All plugin settings are stored in:

atew_settings

Default Settings

| Setting | Default | Purpose | |---|---:|---| | role_slug | tax_exempt | WordPress role slug used for role-based exemption. | | enable_role | 1 | Enables role-based eligibility. | | user_meta_key | _ath_tax_exempt | User meta key used for meta-based eligibility. | | enable_user_meta | 1 | Enables user-meta eligibility. | | enable_certificates | 1 | Enables certificate attachment fields. | | require_valid_certificate | 0 | Requires a valid certificate before exemption is granted. | | cert_meta_id | _ath_tax_exempt_cert_id | User meta key for certificate attachment ID. | | cert_meta_expires | _ath_tax_exempt_cert_expires | User meta key for certificate expiration date. | | enforcement | vat_exempt | Enforcement strategy: vat_exempt or zero_rate. | | zero_rate_tax_class | zero-rate | Tax class slug used in zero-rate mode. | | enable_rest_override | 1 | Enables HTTP header override detection. | | rest_header | X-Ath-Tax-Exempt | Header name used by integrations. | | rest_header_mode | eligible_only | Restricts override to eligible users or allows always-on override. | | enable_order_flag | 1 | Enables order-level exemption flag. | | order_meta_key | _ath_tax_exempt_order | Order meta key for per-order exemption. | | multisite_ensure_role | 1 | Ensures the exempt role exists across multisite contexts. | | multisite_role_sync_members_only | 1 | Syncs role only for users who are already members of a site. | | enable_logging | 0 | Enables WooCommerce logger output under ath-tax-exempt. | | enable_debug_page | 1 | Enables the admin debug panel. |

User Meta

| Meta Key | Default | Purpose | |---|---|---| | Tax-exempt flag | _ath_tax_exempt | Stores yes or no for meta-based eligibility. | | Certificate attachment | _ath_tax_exempt_cert_id | Stores a WordPress attachment ID for the exemption certificate. | | Certificate expiration | _ath_tax_exempt_cert_expires | Stores an optional YYYY-MM-DD expiration date. |

Order Meta

| Meta Key | Default | Purpose | |---|---|---| | Order-level exemption flag | _ath_tax_exempt_order | Stores yes or no for manual per-order exemption. |

Runtime Session Value

| Session Key | Purpose | |---|---| | atew_force_exempt | Stores a request/session-level force flag after a truthy REST header override is captured. |

---

Integration Points

WooCommerce Checkout

The plugin integrates with WooCommerce's native tax-exempt customer flag and then reinforces that decision with cart, shipping, fee, and total-level filters.

WooCommerce Blocks / Store API

The proactive woocommerce_init customer flag update is helpful for flows that read WC()->customer directly, including Blocks or Store API-style checkout behavior.

Customer Service Operations

The user profile fields and order metabox give non-developer staff a controlled way to manage exemption status, documentation, and exceptions.

Finance and Compliance Workflows

Certificate upload and expiration fields provide a lightweight way to associate documentation with account-level exemption status.

Headless Storefronts

REST header override support provides a consistent integration point for custom front ends or connected systems that need to request exemption during checkout.

Multisite Networks

Networked WooCommerce installations can keep the configured role available across sites and reduce role drift for existing site members.

---

Security and Permissions

• Settings access requires manage_woocommerce.
• Debug probe access requires manage_woocommerce and a valid nonce.
• User profile exemption fields require manage_woocommerce.
• Order metabox saves require edit_shop_order and a valid nonce.
• Settings are sanitized before storage.
• Certificate selection uses the WordPress media library.
• REST/header override should be treated as an integration feature and protected by authentication or trusted request controls.

---

Implementation Review Notes

The codebase is compact, understandable, and purpose-built. The architecture is cleanly separated into settings, determination logic, admin UI, order admin controls, and runtime enforcement.

A few review items should be considered before broad production rollout:

1. Shipping tax-status fallback variable: In filter_shipping_rate_tax_status(), the non-exempt branch returns $status, but the method parameter is named $tax_status. This should be corrected to return $tax_status to avoid an undefined variable notice or incorrect fallback behavior.
2. HPOS support: Order admin functionality currently targets legacy shop_order screens and may need HPOS-compatible order metadata and admin UI support for stores fully migrated to custom order tables.
3. Order flag recalculation: The order-level metabox stores the exemption flag, but existing order tax totals may still need an explicit recalculation workflow depending on how the order is edited. The order:{id} context is available for custom code paths.
4. REST override caution: rest_header_mode = always should only be used when the calling system is authenticated and trusted, because it can bypass normal user eligibility.
5. Certificate validation policy: The plugin validates the presence and expiration of a certificate attachment, but it does not inspect the legal contents of the certificate. Operational review is still required.

---