Athenian Admin Order Shipping

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.

5. Admin Workflow

Step 1: Define Services

An admin creates services in WooCommerce > Admin Order Shipping. Each service receives a label, machine-readable code, price, availability mode, context toggles, optional shipping class filters, and pricing behavior.

Example service definitions:

Local Pickup
Code: local_pickup
Price: 0.00
Availability: Admin only
Visible in: Woo admin, CSR

Van Delivery
Code: van_delivery
Price: 25.00
Availability: Admin only
Visible in: Woo admin, CSR
Taxable: yes
Apply Woo free shipping rules: yes

Store Pickup
Code: store_pickup
Price: 0.00
Availability: Admin + frontend
Visible in: Checkout, Woo admin, CSR

Step 2: Calculate Shipping from an Order

On the WooCommerce order editor, an admin uses the Calculate Shipping button in the unified shipping panel. The plugin reads the order items and shipping address, creates a temporary cart context, recalculates WooCommerce packages, and displays available rates.

Step 3: Select Package Rates

For each package, the admin can choose a live WooCommerce rate or one of the eligible admin services. The interface displays the service/rate label, price, package contents, and free-shipping-rule notes where applicable.

Step 4: Apply to the Order

When the admin applies the selected rates, the plugin removes existing shipping lines from the order, creates new WC_Order_Item_Shipping lines for the selected package rates, writes package metadata, recalculates totals, and saves the order.

Step 5: Use Clean Data Downstream

The resulting order shipping lines can be consumed by WooCommerce admin screens, CSR tools, custom dashboards, and REST integrations. Internal metadata is retained for automation/debugging while hidden from ordinary displays.

---

6. Technical Architecture

Plugin Bootstrap

Main file:

athenian-admin-order-shipping.php

The bootstrap performs several important tasks:

• Defines plugin constants.
• Requires WooCommerce.
• Loads the custom shipping method only after WooCommerce initializes shipping abstractions.
• Prevents early fatal errors when WC_Shipping_Method is not available yet.
• Loads the service manager, admin UI, REST controller, and main plugin controller on plugins_loaded.

Version constant:

AOS_VERSION = '1.3.1'

Main Classes

| Class | File | Responsibility | | --- | --- | --- | | AOS_Plugin | includes/class-aos-plugin.php | Singleton controller, WooCommerce hooks, shipping method registration, package rate filtering, REST response extension, metadata display cleanup. | | AOS_Services | includes/class-aos-services.php | Service storage, sanitization, default services, context visibility, package eligibility, free shipping logic, package contents helpers. | | AOS_Admin | includes/class-aos-admin.php | Woo admin service manager, order metabox, unified shipping calculator, AJAX calculation/update handlers. | | AOS_REST | includes/class-aos-rest.php | REST endpoints for service lookup and adding CSR-visible order services. | | AOS_Shipping_Method | includes/class-aos-shipping-method.php | WooCommerce shipping method used to surface frontend-eligible services in shipping zones. |

Included Views

| View | Purpose | | --- | --- | | includes/views/services-page.php | WooCommerce admin service manager page. | | includes/views/services-row.php | Editable row template for each shipping service. | | includes/views/order-metabox.php | Legacy/simple order metabox for adding a single admin shipping service. |

Additional Documentation/Preview Assets

| File | Purpose | | --- | --- | | README.md | Version notes and functional summary. | | admin-order-shipping-product-description.html | Marketing/product description layout. | | admin-order-shipping-render-preview-template.html | Rendered preview/template asset for product presentation. |

---

7. Data Model

Service Storage

Services are stored as a WordPress option:

aos_admin_shipping_services

The option value is an associative array keyed by service code.

Service Object Shape

Each service is normalized by AOS_Services::sanitize_service() into the following structure:

[
    'code'                        => 'van_delivery',
    'label'                       => 'Van Delivery',
    'description'                 => 'Administrative local van delivery.',
    'default_price'               => '25.00',
    'taxable'                     => true,
    'enabled'                     => true,
    'availability'                => 'admin_only',
    'show_on_cart'                => false,
    'show_on_checkout'            => false,
    'show_in_admin'               => true,
    'show_in_csr'                 => true,
    'allow_price_override'        => true,
    'respect_free_shipping_rules' => true,
    'shipping_classes'            => '',
]

Shipping Line Metadata

When selected shipping lines are added to an order, the plugin can store the following metadata:

| Meta Key | Purpose | | --- | --- | | _aos_package_index | Numeric package index selected from the package-rate UI. | | _aos_package_hash | Package hash used to associate selections with package contents/destination. | | _aos_package_id | Optional package ID used by CSR/REST workflows. | | _aos_source | Source of the shipping line, such as woocommerce, admin_service, csr, frontend, or woo_admin_metabox. | | _aos_service_code | Configured service code for admin/CSR services. | | _aos_free_shipping_rule_applied | yes when free-shipping rules caused the rate to become zero. | | _aos_selected_by | WordPress user ID that selected/applied the shipping line. | | _aos_package_contents_summary | Human-readable package contents summary. | | _aos_package_contents_items | JSON-encoded package item payload. | | _aos_shipping_methods_note | Concise note combining service/rate label, price, and package contents. | | Items | Public metadata mirror of package contents summary for REST/order JSON parity. |

The plugin hides the internal _aos_* metadata from normal WooCommerce formatted meta displays while preserving it internally.

REST Response Extension

The plugin adds the following top-level field to WooCommerce order REST responses:

{
  "aos_shipping_packages": [
    {
      "shipping_item_id": 12345,
      "method_title": "Package 1 - Van Delivery",
      "method_id": "admin_order_shipping",
      "total": 25,
      "package_index": "0",
      "package_hash": "...",
      "source": "admin_service",
      "service_code": "van_delivery",
      "free_shipping_applied": false,
      "package_items_summary": "Example Product x 2",
      "package_items": [],
      "shipping_methods_note": "Van Delivery ($25.00) - Example Product x 2"
    }
  ]
}

This is easier for connected systems to read than raw shipping-line metadata.

---

8. WooCommerce Integration Points

Shipping Method Registration

The plugin registers a WooCommerce shipping method:

admin_order_shipping

The method supports:

[ 'shipping-zones', 'instance-settings' ]

This allows frontend-eligible Admin Order Shipping services to be enabled within WooCommerce shipping zones.

Package Rate Filtering

The plugin filters package rates through:

woocommerce_package_rates

This is used to:

• Remove Admin Order Shipping rates that are not visible in the current context.
• Apply free-shipping behavior to eligible admin service rates.
• Inject CSR-visible admin service rates during CSR AJAX workflows.

CSR Context Detection

The plugin treats AJAX actions beginning with aoe_ as CSR context. This is designed to support bespoke CSR order interfaces that calculate, update, rebuild, draft, or refresh pay-order shipping contexts using AJAX.

In CSR context, eligible admin shipping services are injected into package rates so they remain available across cart rebuilds and final order payload generation.

Order Editor Integration

The plugin uses:

woocommerce_admin_order_data_after_shipping_address

This inserts the unified shipping action panel into the WooCommerce order editor. The panel is powered by two admin AJAX actions:

calculate_shipping_for_order
update_order_shipping

Legacy Order Metabox

The plugin also registers a side metabox for adding a single admin shipping service:

Admin Shipping Services

This metabox uses the woocommerce_process_shop_order_meta hook to add the selected service as a shipping line.

---

9. REST API Reference

Get All Services

GET /wp-json/admin-order-shipping/v1/services

Returns the configured service catalog.

Permission: edit_shop_orders or manage_woocommerce

Get CSR-Eligible Services for an Order

GET /wp-json/admin-order-shipping/v1/orders/{id}/services

Returns services visible in the csr context.

Permission: edit_shop_orders or manage_woocommerce

Add a CSR Shipping Service to an Order

POST /wp-json/admin-order-shipping/v1/orders/{id}/services

Supported parameters:

| Parameter | Required | Purpose | | --- | --- | --- | | service_code | Yes | Service code to add. Must be visible in CSR context. | | price | No | Optional price override when service allows override. | | package_id | No | Optional package identifier. | | free_rule_applied | No | Applies zero pricing when the service respects free-shipping rules. | | package_contents_summary | No | Human-readable package contents. | | package_contents_items | No | Structured package item array or JSON string. | | shipping_methods_note | No | Optional shipping note. Generated automatically when omitted and package summary is available. |

The endpoint creates a WC_Order_Item_Shipping, writes AOS metadata, recalculates order totals, and saves the order.

---

10. AJAX Workflow

Calculate Shipping for Order

Action:

wp_ajax_calculate_shipping_for_order

Handler:

AOS_Admin::ajax_calculate_shipping_for_order()

The calculation flow:

1. Verifies the order-specific nonce.
2. Checks edit_shop_order capability for the order.
3. Reads destination fields from the order editor.
4. Resets WooCommerce shipping.
5. Sets the customer shipping location.
6. Empties the current WooCommerce cart.
7. Rebuilds the cart from order line items.
8. Calculates cart totals.
9. Retrieves WooCommerce shipping packages.
10. Adds computed package cost, weight, dimensions, and destination data.
11. Calculates shipping rates.
12. Renders package/rate HTML for admin selection.
13. Empties the temporary cart.

Update Order Shipping

Action:

wp_ajax_update_order_shipping

Handler:

AOS_Admin::ajax_update_order_shipping()

The update flow:

1. Verifies the order-specific nonce.
2. Checks edit_shop_order capability.
3. Validates selected shipping data.
4. Loads the order.
5. Removes existing shipping lines.
6. Creates one new WC_Order_Item_Shipping per selected package/rate.
7. Writes method, cost, package index, package hash, package contents, source, service code, free-shipping status, and selected user metadata.
8. Sets the shipping total.
9. Recalculates totals.
10. Saves the order.
11. Returns the formatted shipping total.

---

12. Security and Permissions

The plugin uses standard WordPress and WooCommerce permission checks throughout the admin, AJAX, and REST layers.

Admin Service Manager

• Requires manage_woocommerce to render and save the service catalog.
• Uses check_admin_referer( 'aos_save_services' ) before saving.
• Sanitizes service fields before storage.

Order Editor AJAX

• Uses order-specific nonces:

'aos_order_shipping_' . $order_id

• Requires edit_shop_order for the specific order.
• Sanitizes destination fields, shipping method values, labels, service codes, package contents summaries, and notes.

REST Endpoints

• Require either edit_shop_orders or manage_woocommerce.
• Validate order existence.
• Verify that requested service codes exist and are visible in the CSR context.
• Enforce allow_price_override and free-shipping-rule behavior.

Metadata Visibility

Internal metadata is hidden through:

woocommerce_hidden_order_itemmeta
woocommerce_order_item_get_formatted_meta_data

This protects normal order displays from becoming cluttered with operational _aos_* fields while preserving the data for systems that need it.

---

14. Technical Strengths

Operationally Realistic Shipping Model

The plugin recognizes that many stores need shipping choices after checkout. Admin teams often need to add local delivery, store pickup, freight, or special handling without forcing customers to see every internal option at checkout.

Package-Level Decision Making

By calculating and writing shipping lines per package, the plugin supports more granular fulfillment workflows than a single manual shipping fee.

Context-Safe Service Exposure

The same service catalog can power admin, CSR, cart, and checkout contexts while preventing accidental exposure of internal services.

REST-Friendly Package Payloads

The aos_shipping_packages payload creates a readable integration surface for connected systems without requiring consumers to parse raw WooCommerce line-item metadata.

Defensive WooCommerce Loading

The plugin avoids the common WooCommerce plugin mistake of loading a shipping method too early. This improves stability during activation, plugin scans, and admin initialization.

Cleaner Admin UX

The plugin preserves internal metadata while showing admins a readable package contents summary underneath shipping lines.

---

15. Implementation Considerations

Existing Shipping Lines Are Replaced

The unified update workflow removes existing shipping lines before adding the selected package-level lines. This is appropriate for a shipping recalculation tool, but teams should understand that it is a replacement workflow rather than an additive-only workflow.

Temporary Cart Dependency

The order editor calculator depends on the WooCommerce cart, customer, and shipping session being available in admin AJAX context. If a site heavily modifies WooCommerce sessions or disables cart context in admin, that behavior should be tested.

Variation Handling Review

The calculation workflow rebuilds the temporary cart from order items using the product ID and quantity. Stores with heavy variation-specific shipping behavior should test whether variation IDs, variation attributes, and custom cart item data need to be preserved in a future enhancement.

Tax Calculation Behavior

Admin services support a taxable setting. Selected shipping line totals are set and the order is recalculated, so behavior should be tested with the store's shipping tax configuration, tax-exempt users, CSR order creation flows, and payment capture workflows.

Frontend Services Require Shipping Zone Setup

Frontend-eligible services are surfaced through the custom WooCommerce shipping method, so the Admin Order Shipping method must be enabled in applicable WooCommerce shipping zones.

---