First Time Setup

TrustLens is designed to work the moment it’s activated — all eight detection modules ship enabled, Card-Testing Defense protects checkout immediately, and scoring runs in the background without configuration. This guide walks through the small number of first-run choices that determine how aggressive scoring is, what the plugin is allowed to do at checkout, and how it talks to you.

Plan to spend about 15 minutes on first-time setup. The only step that takes real wall-clock time is Historical Sync, which runs entirely in the background.

---

The 5-Minute Setup #

If you only have five minutes, do these three things:

1. Run Historical Sync from the Dashboard banner so TrustLens has data about your past customers
2. Open Settings → General and confirm your admin email is correct for notifications
3. Place a test order as a logged-out guest, then check that the new customer appears in TrustLens → Customers

That’s it — TrustLens is now scoring customers, watching for refund and coupon abuse, and protecting checkout against card-testing attacks. Everything else below is optional refinement.

---

Step 1: Run Historical Sync #

Without Historical Sync, TrustLens only sees customer behavior from activation onward. New customers will get scored normally, but every customer who has ever ordered from your store before TrustLens was installed will start with a base score of 50 and an empty event history.

Historical Sync fixes this by reading existing WooCommerce orders, refunds, and disputes in small background batches.

How to Run It #

1. Open TrustLens → Dashboard
2. You’ll see a banner at the top: “No historical data yet. Run Historical Sync to build trust profiles from your existing orders.”
3. Click Run Historical Sync
4. Confirm. The sync queues Action Scheduler jobs and begins processing immediately.
5. Leave the page or keep working — the sync runs in the background

What to Expect #

Store Size	Estimated Sync Time	Notes
< 1,000 orders	2–10 minutes	Usually finishes before you’ve finished reading this guide
1,000–10,000 orders	15–60 minutes	Progress visible on the Dashboard
10,000–100,000 orders	1–6 hours	Runs in batches; no frontend impact
100,000+ orders	6–24 hours	Some hosts throttle WP-Cron; verify Action Scheduler is processing

If Sync Stalls #

If progress hasn’t moved for 30+ minutes:

• Visit WooCommerce → Status → Scheduled Actions and filter to the trustlens/historical_sync_batch hook
• If actions show as pending but never run, WP-Cron may be disabled. Set up a real server cron job hitting wp-cron.php every minute.
• If actions show as failed, check the failure reason — usually a memory limit or a corrupted legacy order
• You can safely re-run sync; TrustLens deduplicates by order ID

---

Step 2: General Settings #

Go to TrustLens → Settings → General. The defaults are tuned for typical e-commerce stores, but three settings are worth confirming.

Minimum Orders for Scoring #

Default: 3

Customers below this threshold stay in the Normal segment regardless of signals. This prevents noisy false positives on customers with only one or two orders — a single refund on a customer with one order shouldn’t drop them into Risk. Raise this to 5 if your store has very generous return policies and you want extra patience; lower to 2 only if you have strong signal quality and need faster classification.

Return-Risk Thresholds #

Defaults: 25% elevated / 40% high / 60% very-high

These thresholds determine when the Returns module starts emitting negative signals. A customer with a 50% return rate hits the “high” tier and loses score points; a customer at 65% hits “very-high” and loses significantly more. The defaults work for most apparel and general retail. If you sell categories with naturally high return rates (e.g. shoes, fashion), consider raising the thresholds 5–10 points.

Checkout Blocking #

Default: Off in Free

Even after you mark a customer as blocked, checkout enforcement only applies if this master toggle is on. Keep it off while you observe a week or two of scoring, then turn it on once you trust the signals. When enabled, blocked customers cannot add items to cart or complete checkout in either Classic or Blocks / Store API.

---

Step 3: Verify Module Defaults #

Go to TrustLens → Settings → Modules. All eight modules are enabled by default. Review them in case any aren’t relevant to your store.

Module	Default	When to Disable
Return Abuse	Enabled	Never — this is the highest-signal module
Order Pattern Analysis	Enabled	Rarely; consider disabling only on stores with extremely unusual ordering cadence
Coupon Abuse	Enabled	If you don’t run coupons or new-customer discounts
Category-Aware Risk	Enabled	If you sell a single product category
Linked Accounts	Enabled	Rarely; multi-account detection is one of the strongest fraud-ring signals
Shipping Anomalies	Enabled	If you ship only to a single country and only to billing addresses
Chargebacks	Enabled	Never — chargeback signals are critical
Card-Testing Defense	Enabled	Only if you have a separate WAF or gateway-level card-testing protection you trust completely

Each module has its own sub-settings (sensitivity, thresholds, velocity windows). The defaults are sensible — leave them alone for the first two weeks, then revisit once you’ve seen real scoring data.

---

Step 4: Card-Testing Defense Tuning #

Card-Testing Defense ships enabled and starts blocking stolen-card attacks immediately. Two settings are worth a quick look.

VIP Customer Bypass #

Default: On

When on, customers in the VIP segment skip velocity checks at checkout. This protects loyal repeat buyers from being caught by aggressive velocity rules during legitimate bursts (e.g. ordering for a team or restocking quickly). Keep this on unless you have a specific reason to lock VIP checkouts.

Velocity Thresholds #

Defaults: 3 declines / 60 seconds, 10 submissions / 60 seconds

These trigger a 60-second lockout on the attacker’s device fingerprint. The defaults catch real card-testing botnets aggressively without significantly affecting normal traffic. Only lower them if you’ve observed an active attack slipping through; only raise them if you have legitimate high-velocity declines (e.g. a payment integration that retries failures aggressively).

Panic Button #

From TrustLens → Card Testing, the red Panic Freeze button halts all checkouts for 15 minutes. Use it if an attack escalates beyond what velocity rules can absorb. The button is one click and reversible — you’ll see a banner across the admin until the freeze lifts or you cancel it manually.

---

Step 5: Notifications #

Go to TrustLens → Notifications.

Core Notifications (Free) #

• Blocked checkout alert — fires when a blocked customer attempts checkout
• Activation summary — one-time email sent shortly after activation
• Weekly protection report — Mondays at 9 AM, summarizing the past week

Confirm the recipient email matches your admin email or a shared ops inbox. Sender name and subject line prefix are customizable.

Pro Notifications #

Pro adds 10 advanced notification types — High-Risk Order Alert, Segment Change Alert, Daily Digest, High-Value Order Alert, Repeat Refunder Alert, Velocity Alert, Score Recovery Alert, New Customer Risk Alert, Monthly Revenue Protection Report, and Chargeback Filed Alert. Each can be toggled independently. See Pro Notification Types for details.

---

Step 6: Chargeback Integration #

If you process payments through Stripe or WooPayments, TrustLens ingests disputes automatically — no setup required. Card brand, dispute reason, and outcome flow into the Chargeback Monitor as webhooks arrive.

For Stripe #

The plugin listens on the standard WooCommerce Stripe webhook endpoint. As long as your Stripe gateway is working, disputes will appear in TrustLens within minutes of being filed. No additional configuration.

For WooPayments #

Same — TrustLens hooks into WooPayments’ dispute events.

For Other Gateways #

If you use PayPal, Square, offline, or a custom gateway, log disputes manually so your monthly ratio stays accurate:

1. Go to TrustLens → Settings → Chargebacks (or the Chargeback Monitor page in Pro)
2. Click Record Dispute
3. Enter the order ID, brand, amount, status, and date
4. Save

Recorded disputes count toward the blended ratio and the per-customer dispute history just like ingested ones.

---

Step 7: Place a Test Order #

The fastest sanity check that everything is wired up:

1. Log out of your store
2. Place a test order as a guest using a test email like [email protected]
3. Complete the order
4. In WordPress admin, go to TrustLens → Customers
5. Search for the email — the customer should appear with a score of 50 (base) and segment Normal
6. Click the customer to see the detail profile, which should show the new order in the event timeline

If the customer appears, scoring is working. Issue a partial refund on the test order and watch the score recalculate (within a minute or two — recalculation is queued, not instant).

---

What to Do in the First Two Weeks #

TrustLens improves with time and data. In the first two weeks after Historical Sync completes:

• Watch the Dashboard daily — look at the high-risk customer list and confirm the customers there are ones you’d genuinely want to flag
• Allowlist your known VIPs — even with the VIP segment, allowlisting locks a customer’s score at 100 and prevents any negative signals, which is useful for top customers
• Don’t enable checkout blocking yet — observe first, enforce second
• Tune thresholds if false positives appear — if you see legitimate customers in Caution or Risk, the return-rate or coupon thresholds may need to move
• Review the weekly protection report — it summarizes signal volume and segment movement, which is the fastest way to see whether scoring matches your gut

Once you trust the scoring, enable checkout blocking and configure automation rules (Pro) to act on what you see.

---

What You Don’t Need to Do #

A few things explicitly do not require setup:

• HMAC keys — generated automatically on activation, rotated when you delete plugin data
• Database tables — created automatically; dbDelta handles upgrades
• Action Scheduler — bundled with WooCommerce; TrustLens just queues into it
• HPOS compatibility — declared automatically
• Privacy tools — registered with WordPress’s standard export/erase workflow on activation

If you’ve never opened the Settings page, TrustLens is still scoring, still protecting checkout, and still ready to use.