Athenian Returns Manager

Developer starting point

This page documents the reviewed Returns Manager source baseline and a representative 1.0.1 deployment capture. It does not claim that a customer return, label, refund, restock, email, or carrier integration has been exercised.

5. Customer Workflow

1. Customer logs into WooCommerce My Account.
2. Customer opens the Returns account area.
3. The plugin lists eligible recent orders based on the configured return window and allowed statuses.
4. Customer selects an order.
5. Customer chooses line items and quantities to return.
6. Customer enters item-level return reasons and optional notes.
7. The plugin creates an ath_rma record in ath_rma_requested status.
8. The original WooCommerce order receives an order note indicating that the customer requested a return.
9. Customer can view existing RMAs from the Returns area.

The v1.0 customer workflow is intentionally simple: the customer first selects an order, then the endpoint reloads to show the line-item picker for that order.

---

6. Admin Workflow

Review

Admins review RMA records under the WooCommerce-connected Returns Manager interface. The list table includes RMA, order, customer, status, refund, and date columns.

Approve and Communicate

The admin can mark an RMA approved, upload or attach a label PDF, and send the customer an email. When the email sends successfully, the plugin updates the status to ath_rma_label_sent.

Receive and Restock

Once a return arrives, the admin can mark the RMA as received. If the restock policy allows it, the plugin updates stock quantities for sellable returned items.

Refund

The refund metabox shows a refund preview based on the original order line items and returned quantities. Admins can create a WooCommerce refund from the RMA screen. The plugin stores the linked refund ID and prevents another refund from being created unless the stored refund metadata is manually cleared or the workflow is expanded later.

Close

After label, receive, restock, refund, and review actions are complete, the admin can close the RMA.

---

7. Technical Architecture

Bootstrap

Main file:

athenian-returns-manager.php

The bootstrap defines constants, declares WooCommerce HPOS compatibility, loads includes/Plugin.php, and initializes the plugin on plugins_loaded.

Declared constants include:

define( 'ATH_RMA_VERSION', '1.0.0' );
define( 'ATH_RMA_FILE', __FILE__ );
define( 'ATH_RMA_DIR', plugin_dir_path( __FILE__ ) );
define( 'ATH_RMA_URL', plugin_dir_url( __FILE__ ) );

Loaded Classes

| File | Responsibility | | --- | --- | | includes/Plugin.php | Main singleton loader and hook registration. | | includes/Utils.php | Settings, RMA ID generation, upload folder creation, eligibility checks, refund calculations, formatting, and HPOS-safe order URLs. | | includes/Installer.php | Activation/deactivation, rewrite flush, default settings seed, upload directory creation. | | includes/PostType.php | ath_rma custom post type and custom RMA statuses. | | includes/Admin.php | Settings screen, RMA metaboxes, list columns, label upload, status actions, restock handler, refund handler, admin-created RMAs. | | includes/Assets.php | Frontend and admin stylesheet registration/enqueue. | | includes/MyAccount.php | WooCommerce My Account endpoint, customer return request form, item picker, customer RMA table. | | includes/Email.php | Customer email send wrapper, placeholders, attachments, order notes, email hooks. | | includes/Hooks.php | Placeholder for future post-purchase hooks. | | includes/OrderAdmin.php | WooCommerce order screen actions and RMA lookup/display. | | includes/Integrations/Octolize.php | Optional Octolize label-detection and materialization bridge. |

---

8. Data Model

Custom Post Type

The plugin registers a private admin-facing custom post type:

ath_rma

It appears in the WooCommerce admin menu and uses shop_order-style capabilities with map_meta_cap enabled.

Core RMA Metadata

| Meta Key | Purpose | | --- | --- | | _ath_rma_id | Human-readable generated RMA ID, using the configured prefix and date. | | _ath_rma_order_id | Linked WooCommerce order ID. | | _ath_rma_user_id | Linked customer/user ID. | | _ath_rma_items | Array of returned line items, product IDs, variation IDs, quantities, sellable flags, reasons, and notes. | | _ath_rma_created_gmt | GMT timestamp for RMA creation. | | _ath_rma_restock_policy | Per-RMA restock policy: inherit, force_yes, or force_no. | | _ath_rma_label_path | Local filesystem path for attached PDF label. | | _ath_rma_label_url | Public URL for attached PDF label. | | _ath_rma_label_source | Label source marker, such as octolize. | | _ath_rma_last_emailed_gmt | Timestamp for the last customer email sent from the RMA. | | _ath_rma_refund_id | Linked WooCommerce refund ID created from the RMA. | | _ath_rma_refund_created_gmt | GMT timestamp for the refund creation. | | _ath_rma_refund_amount | Stored refund amount after WooCommerce refund creation. |

RMA Item Payload

Each item row in _ath_rma_items is normalized by Utils::sanitize_items_payload() into a structure like:

[
    'line_item_id' => 123,
    'product_id'   => 456,
    'variation_id' => 0,
    'qty'          => 1,
    'sellable'     => 'yes',
    'reason'       => 'Wrong size',
    'notes'        => '',
]

This design keeps the return tied to the actual WooCommerce order line item, which is necessary for accurate refunds and partial quantity handling.

---

9. Settings

Settings are stored in the ath_rma_settings option.

| Setting | Default | Purpose | | --- | --- | --- | | enabled | yes | Enables the customer returns portal. | | window_days | 30 | Number of days after order creation/completion in which an order is eligible. | | rma_prefix | ARM | Prefix used when generating RMA IDs. | | label_storage | uploads | Label storage mode; current implementation uses uploads. | | from_name | Site name | Sender name for RMA emails. | | from_email | Admin email | Sender email for RMA emails. | | email_subject | Your return is approved: {rma_id} | Customer email subject template. | | email_heading | Return approved | Email heading template. | | email_body | Configurable text | Email body template with placeholders. | | restock_on_received | yes | Automatically restock sellable items when RMA is received, unless overridden. | | add_order_note | yes | Add WooCommerce order notes when major RMA events occur. | | require_login | yes | Require customer login for the returns portal. | | refund_on_received_default | no | Indicates preference for refunding after receipt; admin still triggers refund manually. | | refund_reason | Return received (RMA {rma_id}) | Refund reason/note template. | | refund_note_to_customer | no | Controls whether refund order notes should be customer-visible. |

---

11. Restock Logic

Restocking is handled separately by the RMA workflow.

When an RMA is marked ath_rma_received, the plugin checks:

• Global setting: restock_on_received
• Per-RMA policy: inherit, force_yes, or force_no
• Item sellable flag: sellable = yes
• Product stock management state

For eligible items, the plugin updates stock with WooCommerce stock helpers and fires:

do_action( 'ath_rma_restocked_item', $rma_post_id, $product->get_id(), $qty, $stock, $new_stock );

This provides a practical extension point for inventory logs, warehouse reporting, supplier accounting, or external ERP sync.

---

12. Label Workflow

Manual PDF Upload

Admins can upload a PDF label from the RMA edit screen. The plugin validates the extension, stores the file in the dedicated RMA label upload folder, and saves both path and URL metadata.

The upload folder is hardened with:

• .htaccess blocking executable PHP-like files
• index.php silence file
• WordPress upload directory creation via wp_mkdir_p()

Octolize Bridge

The optional Octolize bridge is intentionally defensive and dependency-light. Instead of requiring a specific Octolize class, it detects likely Octolize/flexible-shipping plugins by scanning installed plugin metadata.

It can scan WooCommerce order meta for PDF references that look like shipping labels and offers an Attach action from the RMA label metabox.

The bridge supports extension through:

ath_rma_octolize_label_meta_keys

This allows a site-specific integration to provide known meta keys once confirmed in a live Octolize shipping environment.

---

13. Hooks, Filters, and Extension Points

Filters

| Filter | Purpose | | --- | --- | | ath_rma_cap_manage | Override the admin capability required to manage RMAs. Default: manage_woocommerce. | | ath_rma_eligible_order_statuses | Override WooCommerce order statuses eligible for customer returns. Default: completed, processing. | | ath_rma_refund_payload | Modify computed refund payload before refund creation. Useful for shipping, fees, or policy adjustments. | | ath_rma_money_decimals | Override money rounding precision for refund calculations. | | ath_rma_email_placeholders | Add custom email placeholders. | | ath_rma_email_subject | Modify final email subject. | | ath_rma_email_heading | Modify final email heading. | | ath_rma_email_body | Modify final email body. | | ath_rma_email_is_html | Toggle HTML email rendering. | | ath_rma_email_reply_to | Add Reply-To email. | | ath_rma_email_attachments | Add or modify attachments for RMA customer emails. | | ath_rma_email_to | Override destination email address. | | ath_rma_octolize_label_meta_keys | Provide known order meta keys for Octolize label lookup. |

Actions

| Action | Purpose | | --- | --- | | ath_rma_email_sent | Fires after a customer RMA email sends successfully. | | ath_rma_email_failed | Fires after an attempted customer RMA email fails. | | ath_rma_restocked_item | Fires after an item is restocked through the RMA workflow. | | ath_rma_created_from_order | Fires after an admin-created RMA is generated from an order. |

---

14. Security and Operational Safeguards

The plugin includes several practical safeguards:

• Nonces for customer return submission actions.
• Nonces for admin status changes, label upload, label attachment, email send, restock, and refund actions.
• Admin capability checks through Utils::can_manage().
• Customer ownership checks before allowing return requests from My Account.
• PDF-only label uploads by extension validation.
• Dedicated hardened upload directory for return labels.
• Refund creation guard to prevent duplicate refund creation from the same RMA metadata.
• Refund quantity checks to reduce over-refund risk.
• HPOS-safe order edit URLs and WooCommerce CRUD order access.

---

16. Implementation Notes From Inspection

• The customer workflow is intentionally simple in v1.0: the customer selects an order, then reloads the Returns endpoint with ath_rma_order to reveal the line-item picker.
• Refund helpers are line-item aware and use historical order data, which is stronger than recalculating from current product prices.
• Shipping refunds are not included by default. This is a safe initial behavior, but a future settings layer could allow shipping refund policies.
• The refund system stores a single _ath_rma_refund_id, so multiple refunds per RMA are not yet modeled as a first-class workflow.
• The Hooks class currently contains a placeholder thank-you hook for future post-purchase messaging.
• The CSS assets are minimal, leaving room for Athenian theme-token styling, richer admin cards, and customer-facing UX upgrades.
• PHP syntax checks passed for the inspected plugin files.

---

Deployment evidence\n\nObserved deployment version: 1.0.1 on Athenian Spa; 1.0.0 on ThixStrip (Representative active/inactive fleet deployment inventory). The captured deployment archive returns-manager-1.0.1.tar.gz has SHA-256 5968e710198cede0591126153c48a770bb2cabee4b536c3a7f1134724bcaa418. The 1.0.1 capture includes release provenance identifying 1.0.0 as its source baseline and 1.0.1 as the release version. The canonical GitHub main baseline remains 1.0.0, so the 1.0.1 release should be promoted to a reviewed branch before changing the page identity.

Deployment and source parity

Observed deployment version: 1.0.1 on Athenian Spa; 1.0.0 on ThixStrip (Representative active/inactive fleet deployment inventory). The captured deployment archive returns-manager-1.0.1.tar.gz has SHA-256 5968e710198cede0591126153c48a770bb2cabee4b536c3a7f1134724bcaa418. The deployed archive contains 23 runtime files matching the GitHub deployed-release branch after line-ending normalization. The branch has one repository-only .gitignore file; there are no deployed-only files. The 1.0.0 source snapshot remains the reviewed technical reference. The 1.0.1 release branch is now the canonical deployed identity, while ThixStrip remains explicitly documented at 1.0.0.

Live fleet review — 2026-10-07

ThixStrip is active on Returns Manager 1.0.0 with installed main-file SHA-256 9b34c6af1421b467b05ed6a2a38b5139b9be3105da978b2f26c55e20093f5c4b. Athenian Spa is active on 1.0.1 with main-file SHA-256 9352890b43c2b0ffc5fa3482b3605922a0d9fc85d2c356db1472fe8f0894fcdf. The documented deployed release identity is baseline/deployed-1.0.1-20261006 at commit 2c2d0f925e6a0764a16ee7a0ce1910bb6b22c872.

The local comparison shows the core RMA behavior files remain unchanged between the reviewed 1.0.0 and 1.0.1 trees; 1.0.1 adds the Athenian license/update bootstrap and release metadata. ThixStrip currently registers the private ath_rma post type, but the read-only runtime review found zero RMA posts and zero _ath_rma_* metadata rows. No return request, label, email, refund, restock, order, or carrier action was invoked.

Keep ThixStrip explicitly on its site-specific 1.0.0 state until owner confirmation and a separately bounded return-state canary are complete.