Skip to navigation Skip to main content
Free on WordPress.org 4.9 / 5 WordPress.org Explore both Plugins
Free on WordPress.org 4.9 / 5 WordPress.org Explore both Plugins
  • WordPress
    Products
    Smart Cycle DiscountsDiscount automation › TrustLensCustomer trust intel › Cycle AI AIPlain-English campaigns ›
    New pluginComing soon
    Resources & toolsDocs, pricing, support ›
    Smart Cycle Discounts

    Smart Cycle Discounts

    Automate WooCommerce discount campaigns — schedule, target, and measure.

    62%
    Free Pro $59 5 discount types Recurring
    Jump into the page
    How it works Capabilities Promo codes Pricing
    Docs
    Getting started Discount types Scheduling
    Explore Smart Cycle Discounts → Changelog
    TrustLens

    TrustLens

    Customer trust intelligence — score buyers, spot abuse, protect revenue.

    Trust 86
    Free Pro $79 6 segments Abuse detection
    Jump into the page
    How it works Detection Outcomes Pricing
    Docs
    Trust scoring Detection modules Card-testing defense
    Explore TrustLens → Verify a report Changelog

    Cycle AI inside Smart Cycle Discounts

    Describe a sale in plain English — Cycle AI builds the whole campaign.

    “20% off hoodies this weekend”
    Included in Pro Natural language Catalog-aware
    See it work

    Type a sentence, get a ready-to-launch discount campaign that already understands your products, prices, and schedule.

    Live demo How it works
    Meet Cycle AI →

    A new plugin Coming soon

    Something is loading in the lab. Join the list to get the reveal first.

    Notify me on launch →

    Resources & tools

    Everything around the plugins — docs, free tools, and help.

    Learn
    Documentation Pricing & bundle Support
    Free tools
    Discount Calculator Sale Calendar
    Stay current
    SCD changelog TrustLens changelog
    Compare all plans →
    Secure checkout WordPress.org 14-day refund View pricing →
  • Affiliate
    Program
    OverviewHow the program works How it works4 steps from apply to earn Commission details30% · 60-day cookie · recurring
    Get started
    Apply nowOpen Takes ~2 minutes Earnings calculatorEstimate your monthly income FAQPayouts, cookies, renewals
    Resources
    Brand kitLogos, banners, copy, social PlaybookTactics that actually convert FTC disclosureHow to disclose properly Affiliate termsFull program agreement Contact teamOpen the contact form
    Earn 30% recurring on every saleFree to join · 60-day cookie · monthly PayPal payouts Apply now
  • Blog
  • DOCS
    Docs & resources

    Guides, references, and answers for every Webstepper plugin.

    Smart Cycle DiscountsAutomated WooCommerce discount campaigns
    Getting started› Discount types› Cycle AI›
    TrustLensCustomer trust & fraud intelligence
    Trust scoring› Detection modules› Card-testing defense›
    Docs home Guides FAQ Pricing Support
    WordPress tools that solve real problems
  • Contact Us
  • About
    Company

    Our Story

    Founded 2020

    Built by store owners, for store owners. We make WordPress tools that solve real problems.

    Learn more
    Built from experienceTools we use ourselves
    Time is preciousSimple, intuitive UX
    Real supportTalk to the founders
    Legal & contact
    Contact us Privacy policy Terms of service Refund policy
    14-day money-backNo questions asked
Popular requests
  • smart cycle discounts
  • trustlens
  • chargeback protection
GET STARTED

Glossary

1
  • TrustLens Glossary

Detection Modules

10
  • Store Trust Network
  • Card Testing Defense
  • Chargeback Tracking
  • Shipping Anomalies
  • Linked Accounts Detection
  • Category Aware Risk
  • Coupon Abuse Detection
  • Order Pattern Analysis
  • Return Abuse Detection
  • Modules Overview

Card Testing Defense

9
  • Attack History
  • Allowlists
  • Geo Diversity
  • Auto Escalation
  • Fingerprinting
  • VIP Bypass
  • Panic Button
  • Velocity Thresholds
  • Overview

Chargeback Monitor

7
  • Ratio Email Alerts
  • Dispute Evidence Report
  • Chargeback Monitor
  • Manual Dispute Entry
  • Stripe WooPayments Ingestion
  • Card Network Thresholds
  • Chargeback Ratio Alert

Customer Management

7
  • Admin Notes
  • Checkout Enforcement
  • Order Trust Column
  • Bulk Actions
  • Blocking and Allowlisting
  • Customer Detail Profile
  • Customer List

Automation

7
  • Async Dispatch Retries
  • Webhooks and HMAC
  • Rule Inspector
  • Actions Reference
  • Conditions Reference
  • Triggers Reference
  • Automation Overview

Trust Scoring

5
  • Account Age Loyalty Bonus
  • Signals Explained
  • Six Customer Segments
  • The 0–100 Score
  • How Trust Scoring Works
View Categories
  • Home
  • Docs
  • Trustlens
  • Developer Documentation
  • Extending with Custom Modules

Extending with Custom Modules

7 min read

0:00 / 7:42
  • View as Markdown Open this page as plain Markdown (opens in a new tab)
  • Open in ChatGPT Ask questions about this page (opens in a new tab)
  • Open in Claude Ask questions about this page (opens in a new tab)
  • Open in Google AI Studio Ask questions about this page (Google account required) (opens in a new tab)

The TrustLens detection module system is designed to be extensible. Beyond the eight built-in modules, developers can write their own modules that observe custom events, emit signals into the trust score, and respect the standard enable/disable option. This page walks through building a custom module from scratch.


The Module Interface #

Every module extends the abstract TrustLens_Module class (includes/class-module.php):

abstract class TrustLens_Module {
    protected string $id = '';
    protected string $name = '';
    protected bool $is_pro = false;

    public function register_hooks(): void {}
    abstract public function get_signal( string $email_hash, ?object $customer = null ): array;

    public function get_settings_fields(): array {
        return array();
    }

    public function is_enabled(): bool {
        // Pro modules also need an active license.
        return (bool) get_option( "trustlens_module_{$this->id}_enabled", true );
    }

    protected function log_event( string $email_hash, string $event_type, array $data = array(), ?int $order_id = null ): void { ... }
    protected function queue_score_update( string $email_hash, int $delay = 60 ): void { ... }
}

The required method:

  • get_signal( $email_hash, $customer ) — return the module’s current signal contribution for a customer as array( 'score' => int, 'reason' => string ), roughly −50 to +50. $customer is the customer row the score calculator already loaded (null when called directly)

Optional:

  • register_hooks() — wire the module into WordPress/WooCommerce events (the default does nothing, for modules that only contribute a signal)
  • is_enabled() — override if you need custom enable logic

Because the base class declares typed properties and return types, your subclass must match them exactly — protected string $id, register_hooks(): void, and the full get_signal() signature — or PHP stops with a fatal error.


Example: Subscription Churn Risk Module #

Let’s build a custom module that flags customers as risky when they cancel subscriptions soon after signup. The full code:

<?php
/**
 * Subscription Churn Risk Module
 *
 * Flags customers who cancel subscriptions within 30 days of signup.
 */

defined( 'ABSPATH' ) || exit;

class My_Module_Subscription_Churn extends TrustLens_Module {

    protected string $id = 'subscription_churn';
    protected string $name = 'Subscription Churn Risk';

    public function register_hooks(): void {
        add_action(
            'woocommerce_subscription_status_cancelled',
            array( $this, 'handle_cancellation' ),
            10, 1
        );
    }

    public function handle_cancellation( $subscription ) {
        if ( ! $subscription ) {
            return;
        }

        $start_date     = $subscription->get_date( 'start' );
        $cancelled_date = $subscription->get_date( 'cancelled' );
        $days_active    = ( strtotime( $cancelled_date ) - strtotime( $start_date ) ) / DAY_IN_SECONDS;

        if ( $days_active > 30 ) {
            return; // Not "early" cancellation
        }

        $email_hash = wstl_get_email_hash( $subscription->get_billing_email() );
        if ( '' === $email_hash ) {
            return;
        }

        // The events table is the canonical place for module-specific history;
        // get_signal() counts these rows back. log_event() adds the module ID.
        $this->log_event( $email_hash, 'subscription_early_cancel', array(
            'subscription_id' => $subscription->get_id(),
            'days_active'     => (int) $days_active,
        ) );

        // Queue a recalculation (deduplicated, runs about a minute later).
        $this->queue_score_update( $email_hash );
    }

    public function get_signal( string $email_hash, ?object $customer = null ): array {
        global $wpdb;
        $count = (int) $wpdb->get_var( $wpdb->prepare(
            "SELECT COUNT(*) FROM {$wpdb->prefix}trustlens_events
             WHERE email_hash = %s AND event_type = %s",
            $email_hash,
            'subscription_early_cancel'
        ) );

        if ( $count >= 3 ) {
            return array(
                'score'  => -20,
                'reason' => sprintf( '%d subscription early cancellations', $count ),
            );
        }
        if ( $count >= 2 ) {
            return array(
                'score'  => -10,
                'reason' => 'Multiple subscription early cancellations',
            );
        }
        if ( $count === 1 ) {
            return array(
                'score'  => -5,
                'reason' => 'Subscription early cancellation',
            );
        }

        return array( 'score' => 0, 'reason' => '' );
    }
}

Registering the Module #

Hook into the trustlens/register_modules action:

add_action( 'trustlens/register_modules', function( $trustlens ) {
    if ( ! class_exists( 'WC_Subscriptions' ) ) {
        return; // Only register if Subscriptions is active
    }
    $trustlens->register_module( new My_Module_Subscription_Churn() );
} );

The action fires on WordPress init, after the built-in modules are registered and before any module’s hooks are wired, so add your listener earlier (e.g. at plugin load). After registration:

  • It’s enabled by default — the option trustlens_module_subscription_churn_enabled defaults to true. Custom modules don’t appear on the Settings → Detection tab, so to turn one off, set that option to false (e.g. wp option update trustlens_module_subscription_churn_enabled 0)
  • It contributes signals to customer scores (once the customer reaches the Full-confidence Order Threshold — below it only the Returns module runs, unless the trustlens/skip_thin_data_scoring filter says otherwise)
  • Its signals appear in customer profiles under its module ID
  • Automation rules can’t reference it directly — the condition fields are a fixed list — but its effect on trust_score and segment is visible to rules

Helper Functions Available #

Function Use
wstl_get_email_hash($email) Compute the keyed HMAC-SHA256 hash for a customer email
wstl_get_customer($email_hash) Get customer record object
wstl_log_event($hash, $type, $data, $order_id = null) Append to event timeline (or $this->log_event() inside a module, which also records the module ID)
wstl_queue_score_update($hash, $delay = 60) Queue async score recalculation (deduped)
wstl_can_use_pro() Check whether Pro features are unlocked

Storing Module-Specific Data #

Three options for storing data your module needs:

1. The Events Table (Recommended) #

Write module observations to {prefix}trustlens_events via wstl_log_event(). Read counts back at signal time with a simple SELECT COUNT(*). This pattern fits TrustLens’s existing append-only event model and benefits from the existing email_hash and event_type indexes.

2. WordPress Options (Lightweight Per-Store State) #

For settings or store-wide flags your module needs, use the WordPress options API: get_option() / update_option() with a my_module_* prefix.

3. Custom Table (Complex Multi-Row State) #

For complex per-customer data that doesn’t fit the events shape (e.g. composite aggregates), create your own table. Follow WordPress conventions: prefix with {wpdb->prefix}my_module_, use dbDelta() for creation.

There is no built-in per-customer meta table in TrustLens. The events table plus aggregate columns on trustlens_customers cover the patterns the core modules use; mirror that approach in your own modules.


Settings UI Integration #

The base class has a get_settings_fields() method, but nothing in the TrustLens admin renders it — custom modules get no settings section or toggle on the Detection tab. If your module needs settings, register your own options and settings page (or a section on an existing WordPress settings screen).

Reading a setting in your module:

$window_days = (int) get_option( 'my_module_subscription_churn_window', 30 );

Module Lifecycle #

  1. register_hooks(): Called once during init, only if the module is enabled. Wire up your hooks here.
  2. get_signal(): Called each time a customer’s score is recalculated, if the module is enabled. Read state, return signal.

Modules are reinstantiated on every page load (Action Scheduler workers, admin pages, REST requests). Don’t rely on instance state — store everything in the database.


Best Practices #

  • Use the module ID consistently. It appears in signal logs, event data and the customer profile.
  • Don’t fire score recalculations synchronously. Always use wstl_queue_score_update().
  • Handle missing dependencies gracefully. If your module relies on another plugin (Subscriptions, Memberships, etc.), check before registering.
  • Don’t store raw PII. Use hashes consistent with TrustLens’s existing scheme.
  • Respect the enabled option. TrustLens checks is_enabled() before wiring hooks and collecting signals — don’t bypass it.
  • Use Action Scheduler for batch operations. Don’t loop over thousands of records synchronously.

Testing Your Module #

  1. Activate the plugin that registers the module (the module itself is enabled by default)
  2. Trigger a relevant event (e.g. cancel a test subscription)
  3. Verify the event appears in the customer’s Recent activity
  4. Wait 1–2 minutes for score recalculation (or click Recalculate on the profile)
  5. Open the customer’s profile and confirm the signal appears in the Signal impact panel

For automated testing, use the WordPress test suite with mock objects.


Distributing Your Module #

Custom modules can be:

  • Single-purpose plugins (recommended) — separate plugin that depends on TrustLens being active
  • Code in your theme’s functions.php — fine for one-off store customizations
  • Mu-plugins — useful for required customizations across a site

If distributing publicly, follow WordPress plugin guidelines and declare dependency on TrustLens via the Requires Plugins header.


Examples of Custom Modules #

  • Subscription churn (above)
  • External fraud API integration — call an external service, factor result into score
  • Loyalty program tier signal — boost score for active loyalty members
  • B2B order velocity — different scoring for B2B vs B2C customers
  • Promotion participation tracking — flag customers who only buy during sales
  • Customer lifetime value scoring — explicit LTV signal
Updated on October 18, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad

Share This Article :

  • Facebook
  • X
  • LinkedIn
  • Pinterest
Hooks and Filters ReferenceWebhook Payloads
Table of Contents
  • The Module Interface
  • Example: Subscription Churn Risk Module
  • Registering the Module
  • Helper Functions Available
  • Storing Module-Specific Data
    • 1. The Events Table (Recommended)
    • 2. WordPress Options (Lightweight Per-Store State)
    • 3. Custom Table (Complex Multi-Row State)
  • Settings UI Integration
  • Module Lifecycle
  • Best Practices
  • Testing Your Module
  • Distributing Your Module
  • Examples of Custom Modules
Newsletter

Insights that grow your business

Join thousands of WooCommerce store owners who get actionable tips, plugin updates, and industry news every week — plus 10% off either of our plugins as a welcome.

We respect your privacy. Unsubscribe at any time.

10% off welcome gift — A code for either plugin, on us
Weekly updates — Fresh content every Tuesday
Exclusive content — Tips you won't find on our blog
Early access — Be first to know about new plugins
Webstepper
Weekly WooCommerce Tips
Just now
This week: 5 proven strategies to boost your average order value using smart discount campaigns...
10% off inside
Webstepper

Tools for store owners who'd rather grow than grind.

Simple, powerful plugins that help WooCommerce store owners sell more — without the learning curve.

Add Webstepper as a preferred source on Google

Products

  • Smart Cycle Discounts
  • TrustLens
  • Discount Calculator
  • Sale Calendar

Company

  • About Us
  • Blog
  • Contact
  • Affiliates
  • Log In

Resources

  • Help Center
  • Guides
  • Verify a report
  • Affiliate Program
  • Become a Partner

Questions? We actually answer.

Real humans, real help. No bots, no runaround. Usually within a few hours.

Get in touch
Operated by Setmood LLC · 7901 4th St N, St Petersburg, FL 33702 · United States

© 2026 Webstepper. All rights reserved.

Privacy Terms Refunds
Visa Mastercard PayPal Apple Pay Google Pay & more
Limited Time Offer

Get 10% off
Smart Cycle Discounts or TrustLens

Drop your email and we’ll send you a unique, single-use code — works on either plugin at checkout. New customers, first payment.

23 hours
:
59 minutes
:
59 seconds

No spam. Unsubscribe anytime.

  • WordPress
    Back
    Products
    Smart Cycle DiscountsDiscount automation › TrustLensCustomer trust intel › Cycle AI AIPlain-English campaigns ›
    New pluginComing soon
    Resources & toolsDocs, pricing, support ›
    Smart Cycle Discounts

    Smart Cycle Discounts

    Automate WooCommerce discount campaigns — schedule, target, and measure.

    62%
    Free Pro $59 5 discount types Recurring
    Jump into the page
    How it works Capabilities Promo codes Pricing
    Docs
    Getting started Discount types Scheduling
    Explore Smart Cycle Discounts → Changelog
    TrustLens

    TrustLens

    Customer trust intelligence — score buyers, spot abuse, protect revenue.

    Trust 86
    Free Pro $79 6 segments Abuse detection
    Jump into the page
    How it works Detection Outcomes Pricing
    Docs
    Trust scoring Detection modules Card-testing defense
    Explore TrustLens → Verify a report Changelog

    Cycle AI inside Smart Cycle Discounts

    Describe a sale in plain English — Cycle AI builds the whole campaign.

    “20% off hoodies this weekend”
    Included in Pro Natural language Catalog-aware
    See it work

    Type a sentence, get a ready-to-launch discount campaign that already understands your products, prices, and schedule.

    Live demo How it works
    Meet Cycle AI →

    A new plugin Coming soon

    Something is loading in the lab. Join the list to get the reveal first.

    Notify me on launch →

    Resources & tools

    Everything around the plugins — docs, free tools, and help.

    Learn
    Documentation Pricing & bundle Support
    Free tools
    Discount Calculator Sale Calendar
    Stay current
    SCD changelog TrustLens changelog
    Compare all plans →
    Secure checkout WordPress.org 14-day refund View pricing →
  • Affiliate
    Back
    Program
    OverviewHow the program works How it works4 steps from apply to earn Commission details30% · 60-day cookie · recurring
    Get started
    Apply nowOpen Takes ~2 minutes Earnings calculatorEstimate your monthly income FAQPayouts, cookies, renewals
    Resources
    Brand kitLogos, banners, copy, social PlaybookTactics that actually convert FTC disclosureHow to disclose properly Affiliate termsFull program agreement Contact teamOpen the contact form
    Earn 30% recurring on every saleFree to join · 60-day cookie · monthly PayPal payouts Apply now
  • Blog
  • DOCS
    Back
    Docs & resources

    Guides, references, and answers for every Webstepper plugin.

    Smart Cycle DiscountsAutomated WooCommerce discount campaigns
    Getting started› Discount types› Cycle AI›
    TrustLensCustomer trust & fraud intelligence
    Trust scoring› Detection modules› Card-testing defense›
    Docs home Guides FAQ Pricing Support
    WordPress tools that solve real problems
  • Contact Us
  • About
    Back
    Company

    Our Story

    Founded 2020

    Built by store owners, for store owners. We make WordPress tools that solve real problems.

    Learn more
    Built from experienceTools we use ourselves
    Time is preciousSimple, intuitive UX
    Real supportTalk to the founders
    Legal & contact
    Contact us Privacy policy Terms of service Refund policy
    14-day money-backNo questions asked
We use cookies to improve your experience on our website. By browsing this website, you agree to our use of cookies.
More info More info Accept