---
title: Modules Overview
description: "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…"
url: "https://webstepper.io/docs/trustlens/detection-modules/modules-overview/"
updated: "2026-10-18"
category: Detection Modules
---

# 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](/docs/trustlens/detection-modules/return-abuse-detection/) | `returns` | Return rate against your store baseline, refund value, delivered full refunds and other return patterns | Enabled |
| [Order Pattern Analysis](/docs/trustlens/detection-modules/order-pattern-analysis/) | `orders` | Completed orders, order value, cancellation patterns | Enabled |
| [Coupon Abuse](/docs/trustlens/detection-modules/coupon-abuse-detection/) | `coupons` | Refunded coupon orders, first-order coupons, coupon usage rate | Enabled |
| [Category-Aware Risk](/docs/trustlens/detection-modules/category-aware-risk/) | `categories` | Category and product context that scales the Returns penalty (no separate signal) | Enabled |
| [Linked Accounts](/docs/trustlens/detection-modules/linked-accounts-detection/) | `linked_accounts` | Shared address, phone, or payment method (a shared IP or device only corroborates) | Enabled |
| [Shipping Anomalies](/docs/trustlens/detection-modules/shipping-anomalies/) | `shipping_anomalies` | Address hopping, country mismatches, address-change velocity | Enabled |
| [Chargeback Tracking](/docs/trustlens/detection-modules/chargeback-tracking/) | `chargebacks` | Disputes, dispute outcomes, monthly chargeback ratio per card network | Enabled |
| [Card-Testing Defense](/docs/trustlens/detection-modules/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](/docs/trustlens/detection-modules/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](/docs/trustlens/developer-documentation/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.