Modules Overview

TrustLens detection is organized as eight independent modules. Each module watches a specific class of behavior — refunds, orders, coupons, categories, linked accounts, shipping anomalies, chargebacks, and card-testing attacks — and contributes signals to the trust score. Modules run in parallel, can be toggled individually, and each emits signals you can audit on the customer profile. This guide is the orientation document; the detail docs for each module follow.

---

The Eight Modules #

Module	Module ID	What It Watches	Default
Return Abuse	returns	Return rate against your store baseline, refund value, delivered full refunds and other return patterns	Enabled
Order Pattern Analysis	orders	Completed orders, order value, cancellation patterns	Enabled
Coupon Abuse	coupons	Refunded coupon orders, first-order coupons, coupon usage rate	Enabled
Category-Aware Risk	categories	Category and product context that scales the Returns penalty (no separate signal)	Enabled
Linked Accounts	linked_accounts	Shared address, phone, or payment method (a shared IP or device only corroborates)	Enabled
Shipping Anomalies	shipping_anomalies	Address hopping, country mismatches, address-change velocity	Enabled
Chargeback Tracking	chargebacks	Disputes, dispute outcomes, monthly chargeback ratio per card network	Enabled
Card-Testing Defense	card_testing	Decline velocity at checkout, attacker device fingerprints	Enabled

All eight ship in Free. Card-Testing Defense and Chargeback Tracking have Pro enhancements (auto-escalation, Chargeback Monitor page, etc.) but the core detection in both is available without Pro.

A ninth signal, the Store Trust Network, is a Pro, multi-site module rather than one of the eight free modules. If you run more than one WooCommerce store, it lets a customer flagged at one of your stores be recognized at the others. It’s opt-in, off by default, and layers on top of the local modules without changing how they work — so it’s documented separately here.

---

How Modules Work #

Every module except Linked Accounts follows the same interface, defined by the abstract TrustLens_Module class (Linked Accounts is a separate component that adds its penalty through the trustlens/score_signals filter):

• register_hooks() — wires the module into WooCommerce events (order completed, refund issued, coupon applied, etc.) so it can record observations to the customer record
• get_signal($email_hash) — returns the module’s current signal contribution for a given customer: a score delta and a human-readable reason
• get_settings_fields() — declares the settings UI the module exposes
• is_enabled() — checks the per-module enable toggle

The scoring engine calls get_signal() on every enabled module during each recalculation — except that, for customers below the Full-confidence Order Threshold (default 3 orders), only the Returns module runs (confidence-weighted). Modules read from TrustLens’s own tables (the customer record, the refund ledger, the fingerprint table) — not from WooCommerce orders directly — which is why scoring is fast even on stores with millions of orders.

---

Two Phases: Observe and Score #

Modules operate in two phases, separated in time.

Observe (event-driven) #

When a relevant WooCommerce event fires — a refund is created, a coupon is applied, a dispute webhook arrives — the module’s hook callback runs synchronously. The callback:

1. Reads what just happened
2. Updates aggregate counts on the customer’s row (e.g. total_refunds, first_order_coupons, total_disputes)
3. Logs an event to {prefix}trustlens_events for the timeline
4. Queues an asynchronous score recalculation

This phase is fast — single-row updates and one queue insert. No scoring happens here.

Score (async) #

When the queued recalculation runs (typically within 1–2 minutes), the scoring engine calls get_signal() on every enabled module. Each get_signal() reads the customer’s aggregate stats, applies the module’s rules, and returns its current contribution. The engine sums signals, applies the bonus, clamps, and writes the new score.

This separation means a busy event (e.g. ten refunds in a minute) updates the persistent record ten times but only triggers one or two score recalculations. The deduplication is in the queue, not in the observation logic.

---

Module Independence #

Modules mostly work independently. The Coupons module doesn’t know about chargebacks; the Chargebacks module doesn’t know about coupons. The shared surfaces are:

• The customer’s persistent record (stat columns each module owns — notably the order counts kept by the Orders module, which other modules use as their denominator)
• The fingerprint table written by Linked Accounts, which Shipping Anomalies reads for address history
• The product-risk multiplier from Category-Aware Risk and the linked-account list, both used inside the Returns signal
• The score recalculation queue
• A handful of cross-module hooks (e.g. trustlens/linked_accounts_detected, which the Coupons module subscribes to for the “first-order coupons across linked accounts” pattern)

This makes modules easy to reason about in isolation. Most can be disabled and the score simply won’t include that module’s contribution anymore — but turning off Orders stops live order counting, turning off Linked Accounts stops new address data reaching Shipping Anomalies, and turning off Category-Aware Risk sets the Returns multiplier to a neutral 1.0×.

---

Enabling and Disabling Modules #

From TrustLens → Settings → Detection, every module has an on/off toggle (Card-Testing Defense is switched on its own page). The behavior when disabled:

• Hooks are not registered — the module won’t observe new events (the refund ledger is the exception: refunds are recorded even when Return Abuse Detection is off)
• get_signal() is not called — no contribution to scores
• Existing aggregate stats on customer records are preserved — re-enabling resumes scoring without rebuilding
• The module’s card and its settings stay visible on the Detection tab

Disabling a module is reversible. Toggling a module back on doesn’t recalculate existing scores automatically — use bulk recalculate from the customers list, or wait for the next event-triggered recalc.

---

Per-Module Settings #

Module settings live on each module’s card under Settings → Detection, with a few on dedicated screens. Common settings:

Setting Type	Examples
Sensitivity thresholds	Return-rate high / critical thresholds (40 / 60%, on Settings → Refunds), max first-order coupons, linked-account link penalty
Velocity windows	Address change window (7–90 days); card-testing decline and submission thresholds (on the Card-Testing Defense page)
Retention windows	Card-testing event retention (24–168 hours)
Action toggles	“Block checkout when a linked account has used first-order coupons” (Pro), “Auto-block after lost disputes” (Pro, on the Chargeback Monitor page)
Category weights	Per-category multipliers for Category-Aware Risk (Settings → Refunds → Product Risk by Category)

Defaults are tuned for typical e-commerce. Leave them alone for the first two weeks, then adjust based on observed false positives or missed signals.

---

Module Status on the Dashboard #

The Detection Modules panel in the Dashboard’s Command Center shows each module’s state at a glance:

• On/Off state for each of the eight modules, with an “N / 8” active count
• Module settings link — jumps to Settings → Detection

The Command Center’s status bar repeats the “N / 8 modules active” count.

This is the fastest way to verify every module is alive and producing signals.

---

Free vs Pro at the Module Level #

All eight module detection engines are in Free. Pro adds extensions, not replacements:

Module	Free Detection	Pro Adds
Returns	Complete	—
Orders	Complete	—
Coupons	Complete	Checkout block for first-order coupons on linked accounts
Categories	Complete	—
Linked Accounts	Complete	—
Shipping Anomalies	Complete	Diversity-trend detection, multi-country reshipping rule
Chargebacks	Stripe/WooPayments ingestion, manual entry, dashboard alert when a network line is crossed	Dedicated Chargeback Monitor page, per-network breakdown, deadline worklist, Dispute Evidence Report, ratio email alerts, auto-block after N lost
Card-Testing	Velocity detection, escalating device lockouts, Panic Freeze, VIP bypass, browser challenge (Cloudflare Turnstile)	Auto-escalation, geo-diversity safeguard, IP/fingerprint allowlists, 12-font fingerprint, 24-hour attack intelligence, Slack alerts

---

Adding Custom Modules #

The module system is extensible. To add a custom detection module:

1. Create a class extending TrustLens_Module
2. Implement register_hooks() and get_signal()
3. Register it via the trustlens/register_modules action

The custom module’s signals appear in customer signal breakdowns alongside built-in ones, contribute to scores normally, and respect the per-module enable toggle. See Extending with Custom Modules for a full example.

---

Module Performance Profile #

Detection has been engineered for production WooCommerce stores. Some performance characteristics worth knowing:

• Observation overhead per event: typically < 5ms — one indexed UPDATE plus one INSERT into the events table
• Scoring time per customer: typically < 50ms — module signal computations that read the customer’s row plus indexed lookups in TrustLens’s own tables (refund ledger, fingerprints)
• Background work: all scoring happens through Action Scheduler with deduplication so duplicate triggers collapse
• Cache locality: the customer is the unit of work — scoring reads only that customer’s rows, never WooCommerce order tables

The expensive operations run outside the scoring path: Historical Sync in batches, and chargeback ratios computed once and cached.

---

What’s Next #

The following pages dive into each module individually — what it observes, what signals it emits, what settings it exposes, and what false positives to watch for. Start with whichever module is most relevant to your store; they’re independent and can be read in any order.