Theme Modules

This page provides a reference for key theme modules and their responsibilities.

---

MetalPricing (class-metal-pricing.php)

Handles all spot-price retrieval and markup calculation for the Dealers Site.

Key methods:

Method	Description
get_spot_price($metal, $ignore_modifier)	Returns current spot price for a metal (gold, silver, platinum) from WordPress options, with optional spot-price modifier applied
get_markup_modifier($metal)	Returns the per-metal markup modifier stored in options
get_spot_modifier($metal)	Returns the per-metal spot price modifier
calculate_markup($spot, $rate, $modifier, $mode)	Calculates final price given spot, markup rate, modifier, and mode

Spot prices are stored in WordPress options as spot_price_{metal} and spot_price_modifier_{metal}. These are updated by the pricing sync from the Middleware Platform.

The import flow also updates _metal_weight from nFusion payloads so metal-weight dependent pricing and totals remain in sync.

---

WooCommerce\User (class-woocommerce-user.php)

Manages all user-related WooCommerce customisations:

• Company taxonomy — a custom taxonomy company groups users by their dealer company. Used for company-level reporting and admin filtering.
• Admin user columns — adds a Company column to the Users list table.
• Admin user search — extends user search to match billing_company and billing_email meta fields.
• User meta fields — adds custom fields to user profiles (loyalty rates, pricing catalog, account manager, etc.)
• Sub-account defaults — when a sub-account is created via the Subaccounts plugin, sets sensible defaults (e.g., inherits parent pricing catalog).
• Stat summary — renders a purchase statistics summary in the my-account orders section, including Gold/Silver/Platinum YTD ounce totals.
• Account fields — adds custom fields to the WooCommerce account details form.

---

WooCommerce\Order (class-woocommerce-order.php)

Manages order lifecycle, custom statuses, and admin enhancements.

Custom order statuses registered:

Status	Slug	Description
Pending Approval	wc-pending-approval	Order submitted but awaiting admin approval before processing
ACH Pending Payment	wc-pending-ach	ACH payment initiated, awaiting confirmation
Shipped, Not Paid	wc-shipped-not-paid	Net-terms orders shipped before payment clears
Partially Paid	wc-partially-paid	A deposit or partial payment has been received

Other features:

• Removes the "Order Again" button from order detail pages
• Suppresses stock level changes on pending status (stock only reduces on payment)
• Customises buyer display name in admin to show company name instead of personal name
• Adds Date Paid as a sortable column in the admin orders list
• Adds order item metadata (e.g., pricing snapshot) at checkout

---

WooCommerce\ShipStation (class-woocommerce-shipstation.php)

Handles syncing of open orders to ShipStation with correct international customs declarations:

• Strips tax/duty/fee line items from ShipStation payloads (handles them as taxAmount)
• Enriches order items with HS codes and country-of-origin via Tariff::get_tariff_data()
• Supports both production (scottsdale.cc) and staging (wpengine) store IDs
• Marks orders as "fixed" in a custom meta field after processing

---

WooCommerce\Invoice (class-woocommerce-invoice.php)

Extends the WooCommerce PDF Invoices & Packing Slips plugin:

• Adds metal purity as a line-item detail (from _bullet_metal_description product meta)
• Adds custom bullet-point descriptions from _invoice_description product meta to each order line item

---

Integration\TeamAccounts (inc/integration/class-team-accounts.php)

Bridges the Subaccounts & Multi-User Accounts plugin with the Suma theme:

• Ensures sub-account users inherit the correct pricing catalog from the parent account
• Manages shared order visibility (sub-account users can see parent account's orders when configured)

---

Endpoints\Pricing (inc/endpoints/class-pricing.php)

Registers two REST API routes:

Route	Description
GET /suma/v1/spot-prices	Public — returns current gold/silver spot prices and % change
POST /suma/v1/prices	Authenticated — receives price data from the Middleware Platform's HTTP sync target and updates WooCommerce product meta

The /suma/v1/prices endpoint is the receiving side of the Middleware Platform's HTTP Sync Target. The Middleware posts the compact price payload and this endpoint writes prices into WooCommerce product meta (including _metal_weight) using the WooCommerce REST approach.