How TrustLens Automation Rules Work — and When to Use Them

Most automation systems have a documentation problem: they tell you what the feature does but not what happens inside it. You configure a rule, it either fires or it doesn’t, and when it doesn’t, the only recourse is guesswork. Did the condition evaluate the way I expected? Did the trigger even fire? Is something throttling it?

TrustLens Automation Rules is built around a different philosophy. The save-time validator checks whether your rule can ever fire before you save it. The inline inspector logs every evaluation — fired, skipped, or failed — with the specific reason. Between the two, you spend far less time troubleshooting and far more time knowing your store protection is actually working.

This guide covers the mechanics in full: every trigger, every condition field, every action, and the diagnostic layer that keeps the system honest. All figures are verified against TrustLens version 1.2.3 source code. For background on why graduated responses beat hard blocks, the companion post on using TrustLens Automation Rules for graduated fraud response covers the philosophy and four worked examples.

What a TrustLens Automation Rule Actually Is

A TrustLens Automation Rule is a conditional handler with three parts: a trigger, an optional set of conditions, and one action. When the trigger event fires, TrustLens evaluates all enabled rules registered to that trigger. If a rule’s conditions all pass (or it has no conditions), the action executes.

Rules run asynchronously in the background via Action Scheduler — the same background processing system WooCommerce uses for its own jobs. This means a rule firing does not add latency to a customer’s checkout or admin operation. The rule engine picks up the event, queues the work, and your store keeps moving at normal speed.

You can create as many rules as you need, enable or disable them individually, and set different trigger/condition/action combinations for different risk patterns. Each rule operates independently with its own execution history and cooldown state.

The 15 Triggers

A trigger is the event that causes TrustLens to evaluate whether a rule should run. Every enabled rule registered to a trigger is evaluated when that trigger fires. TrustLens Automation Rules supports exactly 15 triggers, across three categories.

Customer lifecycle triggers

These fire when a customer’s status or risk profile changes. They carry only the customer’s email hash — no order object — so they cannot be paired with order-level actions.

• Score Updated — fires every time a customer’s trust score is recalculated, whether the score went up or down. Fires frequently for active customers. Best suited for threshold-based rules (“notify me when any customer’s score drops below 25”) rather than catch-every-change rules.
• Segment Changed — fires only when the customer transitions to a different segment. More selective than Score Updated: if a customer’s score oscillates within the same segment band, this trigger does not fire repeatedly. Use this for rules keyed to a segment transition, such as moving to Risk or Critical.
• Customer Blocked — fires when a customer’s checkout access is removed, whether by a rule or by a manual admin action.
• Customer Unblocked — fires when a block is lifted.
• Customer Allowlisted — fires when a customer is added to the allowlist (score locked at 100, immune to negative signals). Also guaranteed to fire with is_blocked = false, because allowlisting clears any block state.
• Customer Allowlist Removed — fires when an allowlist entry is cleared.

Order and transaction triggers

These fire on a specific order event and carry the order object into the rule evaluation. This unlocks order-level condition fields (order_total, payment_method, shipping_country, etc.) and order-level actions (Hold Order, Cancel Order, Require Verification).

• Order Placed — fires when a customer completes checkout and an order is created. This is the earliest point at which you can hold or cancel an order automatically.
• Order Completed — fires when an order transitions to WooCommerce’s Completed status.
• Refund Processed — fires when a refund is issued against an order.
• Dispute Recorded — fires when a dispute is logged against a specific order (Stripe or WooPayments automatic ingestion, or manual entry on the order edit page). Carries the order object, so you can pair it with order-level conditions and actions.
• Chargeback Filed — fires at the customer level when a chargeback is confirmed. No specific order is attached. Use Dispute Recorded if you need to act on the specific order that generated the chargeback.
• Checkout Blocked — fires when a blocked customer attempts checkout and is prevented from completing it.

Fraud signal triggers

These fire when a TrustLens detection module identifies a specific fraud pattern. They are customer-level triggers and do not carry an order object.

• Linked Accounts Detected — fires when TrustLens identifies that a customer shares fingerprints (shipping address, billing address, phone number, IP address, payment method, or device user-agent) with other customer accounts.
• Card Testing Attack — fires when a card-testing attack is detected at checkout and can be attributed to a specific customer email. Attacks from devices with no associated email do not route to this trigger.
• Shipping Anomaly — fires when the Shipping Address Anomalies module detects unusual address behavior — address hopping, billing/shipping country mismatches, or address-change velocity — for a customer.

The 22 Condition Fields

Conditions are optional filters that narrow when a rule executes. A rule with no conditions fires for every customer who hits the trigger. A rule with conditions only fires when all conditions pass simultaneously.

TrustLens Automation Rules supports 22 condition fields. Sixteen read from the customer’s behavioral record and are available on any trigger. Six read from an order and are only available when the trigger carries one.

Customer-level condition fields (16)

Order-level condition fields (6)

These read from the order context and are only available when the trigger carries an order: Order Placed, Order Completed, Refund Processed, or Dispute Recorded.

Operators, AND Logic, and What That Means for Rule Design

All conditions within a single rule use AND logic: every condition must be true for the rule to fire. If you need OR logic — fire the rule when condition A is true OR condition B is true — create two separate rules, each with one branch of the condition set and the same action.

Numeric fields (trust_score, return_rate, total_orders, and the rest of the count and value fields) support six comparison operators: <, <=, =, !=, >=, >. String and enum fields (segment, customer_type, payment_method, shipping_country, billing_country) support equality operators only: = and !=. Boolean fields (country_mismatch, is_first_order, is_blocked) also use = and !=, with true, 1, or yes interpreted as true.

Two useful patterns come from combining conditions on the same trigger:

• Range conditions: to match a score between 20 and 40, use two conditions on trust_score — one with >= 20 and one with <= 40. Both must be true simultaneously, which defines the range.
• Exclusions with history: to match newer customers without catching completely empty profiles, combine total_orders >= 1 with total_orders <= 5.

The save-time validator catches obvious contradictions before you save. Cross-field semantic dependencies that the data model guarantees are also checked: a total_orders = 0 constraint means the order value must also be zero, and an is_first_order = true constraint means total order count cannot exceed one.

The 10 Actions

When a rule’s conditions all pass, one action executes. TrustLens Automation Rules supports exactly 10 actions. Seven operate at the customer level; three operate at the order level and require one of the four order-bearing triggers.

Customer-level actions

• Block Customer — prevents the customer from adding items to cart or completing checkout. Works on both Classic and Blocks / Store API checkout. The block reason can be set in the action value field; it defaults to “Automated: Rule triggered” if left blank. The block is fully reversible from the customer profile at any time.
• Allowlist Customer — locks the customer’s trust score at 100 and prevents any negative signals from affecting it. Use this for rules that confirm a customer is definitively safe — for example, after a manual review clears a suspected false positive.
• Flag for Review — adds the customer to your watch list by appending a timestamped note to their admin notes. The dashboard’s watch view surfaces these entries. No checkout restriction is applied; this is a soft signal for human attention.
• Send Email — sends an alert email containing the customer’s email hash, trust score, segment, and a link to their profile in the TrustLens admin. The recipient defaults to the site notification email. You can set a per-rule override recipient address in the action value field — useful for routing alerts to a specific team inbox.
• Add Note — appends a timestamped note to the customer’s admin notes without adding them to the watch list. Useful for logging the reason a rule fired without creating a watch-list entry.
• Add Tag — appends a tag to the customer’s admin notes using the value you specify in the action value field. Tags can be used to group customers or to track which rule last acted on a profile.
• Send Webhook — dispatches an async HTTP POST to a URL you specify in the action value field. The payload includes the rule name and ID, the triggering event name, the customer’s email hash, trust score, and segment. Webhooks are HMAC-SHA256 signed by default (covering timestamp + body, with an X-TrustLens-Signature header and an X-TrustLens-Timestamp header). Failed deliveries are retried up to three times with exponential backoff: 60 seconds, then 120, then 240.

Order-level actions

• Hold Order — transitions the specific order to WooCommerce’s “on-hold” status with an order note: “TrustLens: Automation rule triggered — order held for review.” The customer receives WooCommerce’s standard on-hold notification. The order stays in your queue until you manually decide to continue or cancel it. This is the most commonly configured first rule because it is completely reversible.
• Cancel Order — cancels the specific order immediately, with a note naming the automation rule that triggered the cancellation. Use this for high-confidence signals where the store policy is clear enough to automate the outcome.
• Require Verification — marks the order with a _trustlens_requires_verification order meta field and adds an order note. The order is not automatically put on hold — the flag is a signal for your fulfilment team to follow up before processing. Any system that can read WooCommerce order meta can detect this flag.

The Save-Time Validator: Impossible Rules Caught Before They Save

One of the most common problems with rules engines is silent failure: you configure a rule, it sits in your list looking active, and it simply never fires because the conditions can never simultaneously be true. You only discover this after a risk event you expected to catch passes through without triggering anything.

TrustLens validates every rule before saving it. If the validator finds a problem, the save is blocked and you see an explanation of exactly what is wrong. There are four classes of check.

Per-row validity

Each condition row is checked in isolation. For enum and boolean fields (segment, customer_type, is_first_order, etc.), ordering operators like > and < are meaningless — the validator rejects them with a message explaining which operators are valid for that field type. For numeric fields, the value must fall within the column’s schema bounds: you cannot set trust_score > 100 (there is no score above 100) or return_rate < 0 (rates cannot be negative).

Trigger-state contradictions

Some triggers fire after a state transition that guarantees a specific field value. The Customer Blocked trigger guarantees the customer’s is_blocked field is true when it fires. If you add a condition requiring is_blocked = false, that condition can never be true when the trigger fires. The validator catches this and explains it: “When ‘customer_blocked’ fires, ‘is_blocked’ is guaranteed to be true — this condition can never match.”

The same applies to Customer Unblocked and Customer Allowlisted (both guarantee is_blocked = false).

Same-field contradictions

If you add two constraints on the same field whose intersection is empty, the validator catches it. Classic examples: trust_score > 80 AND trust_score < 30 (no value satisfies both), or segment = Risk AND segment = VIP (a customer cannot be in two segments simultaneously).

Cross-field contradictions

For fields where the data model guarantees a dependency, the validator catches cross-field impossibilities. If total_orders = 0, then total_order_value, total_refunds, return_rate, and several other counters are also guaranteed to be zero — a constraint requiring any of those to be positive is impossible alongside it. Similarly, is_first_order = true means total_orders cannot exceed 1.

The Rule Inspector: Why a Rule Fired, Skipped, or Errored

After the save-time validator prevents logically impossible rules, the rule inspector handles the runtime diagnostic layer. Every time a rule is evaluated — whether it fires or not — TrustLens writes a log row. You can see this log for any rule from TrustLens → Automation.

There are three outcomes a log row can report:

• ok — the rule fired and the action succeeded. The row includes the execution duration in milliseconds.
• skipped — the rule was evaluated but did not fire. The row includes the specific reason: either the exact condition that failed (“Condition not met: trust_score >= 50”) or a system-level reason like “Cooldown active.”
• error — the rule fired but the action failed. For webhook actions, this includes the HTTP status code and response error message. For email actions, it includes the PHP mail error when available.

The inspector also covers guest orders. If a customer-level action (block, email, tag) on an order-bearing trigger did not fire because the order was a guest checkout with no TrustLens customer record, the log records “Guest order: no customer email hash.” Order-level actions (hold, cancel, verify) can still fire on guest orders because they act on the order object rather than a customer profile. For more on how TrustLens tracks customers across guest and registered checkouts, the guide to TrustLens customer scoring covers how email-hash tracking works for guests.

The inspector gives you something most automation systems lack: a direct answer to “why didn’t my rule fire?” You do not have to guess at operator precedence or wonder whether your condition values were interpreted the way you expected. Read the log row and you know. This is also a significant improvement over the manual enforcement pattern — as the post on TrustLens segments describes, knowing which tier a customer sits in is only useful if the system can act on it — and if you can verify that it did.

The Cooldown Window and How to Work With It

By default, the same rule will not fire again for the same customer within one hour of the previous execution. The cooldown key is specific to the rule and the customer — other customers can still trigger the same rule, and the same customer can still trigger other rules. Only the exact rule-and-customer pair is suppressed during the window.

The cooldown prevents a burst of rapid events from triggering the same action repeatedly. The most common example is the Score Updated trigger: a batch refund operation might cause three or four score recalculations in quick succession. Without the cooldown, a send-email rule would dispatch three or four nearly identical alerts. With the cooldown, the first evaluation fires the rule, and subsequent evaluations are logged as “Cooldown active.”

One important detail about error handling: if an action fails (a webhook times out, an email cannot be sent), the cooldown is released rather than kept. The rationale is that the failure was not the customer’s fault — suppressing the rule for an hour because the SMTP server was briefly down would silently miss the next real risk event. A failed action releases the cooldown window so the next trigger event for that customer can retry.

The cooldown window can be adjusted via the trustlens/automation/rule_cooldown WordPress filter if your use case requires a different window.

Async Dispatch and Webhook Reliability

All rule actions execute asynchronously via Action Scheduler. For most actions (block, hold, email, tag), this means the work happens out of the request cycle so it does not add latency to checkouts or admin pages. For webhook actions, there is additional reliability machinery worth knowing about.

When a webhook fires, TrustLens first deduplicates the dispatch: if the same trigger fires multiple times for the same customer within a short window — a common pattern during batch operations — only one webhook delivery is queued. The dedup is based on exact argument matching; retries carry a distinct retry counter and bypass dedup so failed deliveries still get their retry attempts.

If the webhook endpoint returns a non-2xx response or the request fails entirely, TrustLens retries up to three times: after 60 seconds, then 120, then 240. If all three retries exhaust, the final failure is logged in the inspector with the specific HTTP status code or error message.

Webhook payloads are signed by default. TrustLens uses a per-install HMAC-SHA256 secret and signs every outbound automation webhook as sha256=hmac(timestamp + '.' + body, secret). The signature is in the X-TrustLens-Signature header; the timestamp is in the X-TrustLens-Timestamp header. On your receiver side, verify the signature and check that the timestamp is within your acceptable window (5 minutes is a common choice) to reject replayed deliveries. This v2 signature scheme ships as of TrustLens 1.2.3.

Practical Rule Patterns Worth Knowing

The table below summarizes how the system’s components combine into useful patterns. None of these are requirements — they are illustrations of the trigger-condition-action combinations that store owners configure most often.

For a deeper look at the graduated-enforcement approach — why you might layer these patterns rather than jumping straight to blocking — the post on TrustLens graduated fraud response works through four of these patterns with full operational context. And for making sense of what each segment threshold means, reading a TrustLens customer profile covers the signal breakdown behind each risk tier.

Frequently Asked Questions

Can one trigger fire multiple rules at the same time?

Yes. When a trigger fires, TrustLens evaluates all enabled rules registered to that trigger. Each rule that passes its conditions will execute its action. If you have three rules registered to Order Placed, all three are evaluated on every order placement, and any whose conditions match will fire independently.

What happens if I use an order-level condition field on a trigger that does not carry an order?

The condition evaluates to false and the rule is skipped. The inspector logs the skip with a “Condition not met” reason pointing to the specific field. The save-time validator does not block this combination (it is not a logical impossibility, because the trigger could theoretically be changed), but the inspector makes the problem visible immediately the first time the rule is evaluated.

Is there a way to test a rule without waiting for a real event?

TrustLens does not include a manual trigger button in the current version (1.2.3). The practical approach is to create a monitoring rule first — a Send Email or Add Note action with the same trigger and conditions as your intended enforcement rule. Run it for several days and watch the inspector log to see which evaluations fire, which skip, and why. Once you are confident the conditions are selecting the right customers, create the enforcement rule alongside it.

Why does the validator say my rule “can never fire” when the conditions look correct?

The most common causes are: ordering operators (>, <) applied to enum fields like segment or customer_type (only = and != are valid there); a numeric value outside the field’s schema bounds (trust_score > 100 is impossible); or a trigger-state contradiction where the trigger guarantees a specific field state that your condition contradicts. Read the specific reason the validator returns — it identifies the exact field and the exact issue.

How is customer_age_days calculated?

TrustLens calculates customer_age_days as the number of whole days between the customer’s first order date and the current moment, both anchored to UTC. The UTC anchoring was added in version 1.2.3 to fix a bug where sites on non-UTC WordPress timezones could see up to 14 hours of drift — enough to push a daily-granularity condition off by a full day. If your store is on a non-UTC timezone and you used customer_age_days conditions before 1.2.3, the values should be more accurate after upgrading.

Can automation rules trigger each other?

Indirectly, yes. If a block_customer action fires from one rule, it emits the trustlens/customer_blocked hook, which in turn evaluates any rules registered to the Customer Blocked trigger. TrustLens handles the re-entrancy risk: the cooldown for the first rule is set before the action executes, so rule A will not re-fire for the same customer during the cooldown window even if its trigger is emitted as a side effect of the action. A Customer Blocked rule that sends a webhook is a common and useful pattern; a Customer Blocked rule that also calls Block Customer would be redundant and is caught by the same cooldown.