How to Use TrustLens Historical Sync to Build Customer Trust Profiles From Day One

When you install TrustLens, it starts scoring customers immediately — but only from the moment it activates. Every order placed before that moment is invisible to it. Your store might have three years of order history, thousands of customers, patterns that tell you exactly who the serial returners and the genuinely loyal buyers are — and none of that shows up yet.

That is what the TrustLens Historical Sync is for. It processes your existing WooCommerce orders in the background and builds behavioral trust profiles for every customer who placed an order before you installed the plugin. When it finishes, TrustLens looks as though it has been running for as long as your store has — because the profiles are built from real historical data, using the original timestamps.

This post covers how the sync works under the hood, how to run it, what to look at when it completes, and one important edge case you should know about before you ever need to discover it the hard way.

What TrustLens Historical Sync Actually Builds

TrustLens Historical Sync is a background process that reads your existing WooCommerce order data and constructs a behavioral profile for each customer it finds. The result is not a summary statistic — it is a full trust profile, the same kind TrustLens would have built had it been running since that customer placed their first order.

For each customer, the sync calculates and stores:

• Order history metrics — total completed orders, total order value, cancellation count, date of first and last order
• Refund behavior — total refunds, full-refund vs. partial-refund breakdown, total refund value, and the return rate percentage that feeds directly into the trust score
• Coupon abuse signals — whether the customer used a coupon on their first order, and whether any order involved a coupon followed by a refund (the coupon-then-refund pattern)
• Category-level purchase and return data — per product category, how many orders and refunds the customer has, so the category-aware risk module can spot high return rates in specific parts of your catalog
• Linked-account fingerprints — shipping address, billing address, phone number, IP address, and payment method hashes, so multi-account fraud rings show up even if the accounts predate your TrustLens installation
• Card-brand data — for Stripe and WooPayments orders, the payment card brand is captured per order so the Chargeback Ratio Speedometer and the Pro Chargeback Monitor have a full historical baseline to work from
• A complete event timeline — order created, order completed, order cancelled, coupon used, full refund, and partial refund events, each dated at the original WooCommerce timestamp. This is what makes the customer profile timeline look accurate rather than showing “no history before install date.”

After building all of this, the sync queues a trust score calculation for every customer. By the time the score appears on their profile, it reflects their full behavioral history, not just activity since you installed TrustLens.

What the sync does not backfill

The sync reads WooCommerce order data — completed, processing, refunded, and cancelled orders. It does not ingest chargeback or dispute records from historical periods unless those records were already manually entered or imported through the chargeback tracking workflow. If you have dispute history you want included, record those chargebacks manually on the relevant orders before running the sync.

Why It Matters More Than You Might Expect

The practical difference between running Historical Sync and not running it is substantial, and it goes in both directions.

On the risk side: without the sync, a customer who placed seven orders before you installed TrustLens and refunded five of them looks identical to a brand-new account with no history. TrustLens will not classify them as high-risk until they exhibit the same behavior again under your watch — which, for a serial returner, they will.

On the trust side: a customer who has ordered from you faithfully for three years starts at the same neutral-50 score as someone who registered yesterday. The loyalty bonus that account age provides will accumulate over time, but their behavioral history — the dozens of completed orders, the zero refunds — does not contribute until the sync runs. Your highest-quality customers will read as “Normal” rather than “VIP” or “Trusted” until TrustLens has seen their full record.

The sync fixes both problems at once. It gives TrustLens enough context to classify your existing customers correctly — which makes the dashboard meaningful from day one rather than requiring weeks of observation before the data settles.

How to Run It: A Step-by-Step Walkthrough

Historical Sync lives on the TrustLens dashboard. You do not need to navigate to a separate settings page — it is the most prominent feature of the empty-state dashboard that greets you after installation.

1. Open TrustLens → Dashboard in the WordPress admin

   If TrustLens has not analyzed any customers yet, you will see the onboarding card. Above the sync button, a chip shows how many WooCommerce orders are queued to be processed. This includes completed, processing, refunded, and cancelled orders.

2. Click “Start Historical Sync”

   The button is in the lower section of the onboarding card. One click starts the process. You do not need to configure anything beforehand — the sync uses your current TrustLens settings, which are set to sensible defaults on install.

3. Watch the progress bar update in real time

   The dashboard shows a live progress bar and a counter of processed orders vs. total orders. Progress updates as each batch completes. The browser drives the progress loop during the sync, so keeping the tab open gives you real-time feedback — but the sync will continue running in the background via Action Scheduler even if you navigate away.

4. Wait for the “Sync complete!” confirmation

   When every order has been processed, the progress bar fills to 100% and the status updates. The dashboard then shows your full customer distribution, trust score trends, and any flagged customers — reflecting the complete picture of your order history.

What Happens While It Is Running

Understanding the mechanics helps you set realistic expectations about how long it will take and what you will see on your dashboard while it is in progress.

How the batches work

TrustLens Historical Sync processes orders in batches of 10 at a time during the browser-driven phase. For each batch, the plugin fetches the orders, identifies the unique customers in that batch, builds or updates their profile rows, rebuilds their category statistics, rebuilds their event timeline, and queues a trust score recalculation for each customer via Action Scheduler.

Action Scheduler — the same background job system WooCommerce uses for its own processing — handles the score calculations asynchronously, which means scores may not appear on customer profiles immediately after the sync finishes. Depending on your server’s Action Scheduler throughput, there can be a short delay of a few minutes between the sync completing and final scores appearing across all customer profiles.

How long it takes

Duration depends almost entirely on your order volume. For most stores, the rough guideline is:

• Under 1,000 orders: typically completes in under 10 minutes
• 1,000–5,000 orders: usually 15–45 minutes
• 5,000–20,000 orders: one to two hours is common
• 20,000+ orders: plan for several hours on shared hosting; significantly faster on dedicated infrastructure

These are rough estimates — actual time depends on your server resources, the number of unique customers per order batch, and how complex each customer’s historical record is to aggregate.

Frontend impact while running

None. The sync runs entirely on the server side through Action Scheduler. There are no frontend JavaScript executions, no product or cart hooks, and no customer-facing requests involved. Your store functions normally while the sync is in progress.

What to Do After the Sync Completes

The dashboard transformation after a successful sync is usually the most informative moment you will have with TrustLens for a while. Here is what to look at and in what order.

Check your segment distribution first

The doughnut chart on the dashboard shows how your existing customer base breaks down across the six trust segments — VIP, Trusted, Normal, Caution, Risk, and Critical. This is the most useful first read because it tells you whether your store has a typical distribution or an unusual one.

Most stores see a large Normal cluster, a meaningful Trusted and VIP group, and a small but real tail of Caution, Risk, and Critical customers. If you see an unexpectedly large Caution or Risk population, that is usually a signal that your return or refund rates are genuinely elevated in some segment of your catalog — worth investigating before adjusting thresholds.

Look at the high-risk customer list

The dashboard surfaces a list of customers currently in the Risk or Critical segment. Open a few profiles and look at the specific signals that moved their scores — the signal impact bars on the customer profile page show exactly which behaviors contributed, and by how much. This is where you will find your most valuable early information: the customer who has refunded on seven of eight orders, the account linked to three other accounts at the same shipping address, the first-order coupon repeater.

Before taking any action on these customers, read the signal breakdown carefully. A high-risk score based entirely on a single category of behavior (say, a high return rate in a legitimately high-return category like clothing) is different from a score built from multiple corroborating signals. The former might warrant a threshold adjustment; the latter is a more reliable indicator of actual risk.

Check the minimum-orders threshold against your data

TrustLens requires a minimum number of orders before it classifies a customer outside of the Normal segment. The default is 3 orders. After the sync, look at how many customers fall below that threshold — and consider whether the default is well-calibrated for your store. A marketplace selling high-value goods might lower this to 1; a subscription store where the behavioral pattern only becomes clear over many orders might raise it. The sync gives you enough data to make that call with confidence rather than guessing.

Review the chargeback baseline (if relevant)

If you process payments through Stripe or WooPayments, the sync backfills card-brand data for your historical orders. This means the Chargeback Ratio Speedometer on the dashboard now has a more complete denominator — the count of completed orders by card brand — which makes your ratio calculation more accurate. If the number looks different from what you expected, that is usually an improvement in accuracy rather than a problem with the sync.

When You Should Run Historical Sync Again

For most stores, Historical Sync is a one-time operation. TrustLens tracks all new orders automatically after activation, so the sync is not a maintenance task you need to repeat on a schedule.

There are a few specific situations where re-running it makes sense:

After importing orders from another platform

If you migrated your store from another platform and imported historical orders into WooCommerce in bulk, those orders existed before TrustLens was activated and will not have been analyzed. A sync run after the import processes them and builds profiles from the imported data.

After a TrustLens data reset

If you use the Reset function in TrustLens settings to clear all customer data and start fresh — for instance, when moving from a staging environment to production — you will need to run the sync again to rebuild profiles from your existing WooCommerce orders.

After the secret-key edge case (covered next)

There is one specific technical scenario involving WordPress secret key rotation that requires a re-sync. Because it is important to understand, it has its own section below.

After extended periods of inactivity

If TrustLens was disabled for a period and then re-activated, the sync will process any orders that came in during the inactive period that TrustLens missed. In practice, this is the same as the initial activation scenario — any order gap gets covered by running the sync again. The sync is idempotent for existing customers: re-running it updates their profiles based on the current order data rather than duplicating records.

Edge Case: WordPress Secret-Key Rotation

This section covers an uncommon but important technical scenario. Most store owners will never encounter it. If you have no plans to rotate your WordPress secret keys, you can treat this as background knowledge and move on.

Why TrustLens uses WordPress secret keys

TrustLens identifies customers using HMAC-SHA256 hashes of their email addresses. The hashing uses your WordPress auth secret key as the keying material. This is a deliberate privacy and security choice: the stored hashes are not reversible, and they are specific to your site — the same email address produces a different hash on a different WordPress installation.

What happens if you rotate the keys

WordPress secret keys can be regenerated — either manually in wp-config.php or via a security plugin’s “regenerate keys” function. When the auth key changes, every HMAC hash that TrustLens has stored becomes invalid. The plugin can no longer match a returning customer to their existing trust profile, because the hash it computes from their email address no longer matches the hash stored in its customer table.

The practical effect: after a key rotation, TrustLens effectively loses track of its entire customer history. Returning customers appear as new unknown customers, linked-account detection stops working for previously identified connections, and the dashboard shows a blank or empty state.

How to recover

Run Historical Sync after any WordPress secret-key rotation. The sync rebuilds all customer hashes and profiles using the new key, restoring the behavioral history from your WooCommerce order records.

Two things worth knowing before you do this:

1. Allowlisted and manually blocked customers are the exception. Manual allowlist and block status is stored per customer row. After a re-sync, the customer rows are rebuilt from order data, but the allowlist/block flags attached to old (now-invalidated) hash values will not automatically carry over to the new hash values. You will need to re-apply any manual allowlist or block status after the sync completes.
2. The sync fully rebuilds linked-account fingerprints. Linked-account connections detected from historical orders will be re-established by the re-sync. Connections that were detected from live events after installation (but before the key rotation) will be rebuilt only if there is corresponding WooCommerce order data to support them.

This behavior is documented in the TrustLens readme.txt FAQ. It is worth knowing about in advance because discovering it reactively — after a key rotation leaves TrustLens unable to recognize customers — is a much more stressful situation than understanding it proactively.

Frequently Asked Questions

Will the sync affect my site’s performance while it runs?

No. Historical Sync processes orders through Action Scheduler in the background. It has no frontend footprint — no JavaScript runs on your storefront, no product or cart hooks are triggered. The only performance consideration is on the server side, where Action Scheduler uses PHP and database resources to process batches. On shared hosting, this is handled gradually enough that it does not cause perceptible slowdown. On dedicated or managed infrastructure, the processing is faster and the impact is lower.

Can I use TrustLens before the sync finishes?

Yes. TrustLens begins scoring new orders from the moment of activation regardless of whether the sync has run. The sync specifically covers pre-activation history. If a new order comes in while the sync is running, it will be processed normally and its customer will get a trust score that reflects both their historical profile (built by the sync) and their new order.

What if I have guest checkout orders without email addresses?

The sync skips orders where no billing email can be found. For stores that allow genuinely anonymous orders (no email required), those orders simply will not contribute to any customer profile. In practice, most WooCommerce setups require an email address even for guest checkout, so this rarely affects a significant portion of order history.

Does the sync work with WooCommerce HPOS?

Yes. TrustLens Historical Sync is fully compatible with WooCommerce High-Performance Order Storage. It uses wc_get_orders() and WooCommerce’s order abstraction layer throughout, rather than querying post tables directly, so it works correctly with both legacy and HPOS-enabled stores.

What happens if the sync encounters an error partway through?

The sync is wrapped in error handling that catches unexpected failures. If a batch fails, the sync transitions to a “failed” state rather than hanging at “running” indefinitely. The dashboard will show the failure with an error message, and you can retry from the same button. The retry continues from the last successfully completed page — you will not need to re-process already-synced orders.

Can I run the sync on a store that has been running TrustLens for a while?

Yes, and the sync handles existing customer records gracefully. If TrustLens has been tracking a customer through live events and then the sync processes that customer’s historical orders, the sync updates their existing profile row rather than creating a duplicate. The event timeline is rebuilt idempotently — previously inserted sync events are removed and re-created from the current order data, so timelines stay clean even after multiple sync runs.

One Last Thought

Historical Sync is one of those features that does most of its work invisibly. You click a button, wait for a progress bar, and then look at a dashboard that suddenly shows you a real picture of your customer base. It does not feel dramatic.

What it actually delivers is the difference between a fraud-prevention tool that has to learn your customers from scratch and one that already knows them. That context matters enormously for the quality of the signals TrustLens surfaces — and for how useful the dashboard is in the weeks after you install it.

If you have not run it yet, it is worth doing before you start adjusting scoring thresholds or making decisions about individual customers. The data it surfaces will inform those decisions far better than the defaults can.

For a deeper look at how TrustLens builds trust scores from behavioral signals, How TrustLens Scores a WooCommerce Customer explains the full scoring model and what each signal contributes. And if you are weighing whether to use the free version or upgrade to Pro, TrustLens Free vs. Pro lays out the practical difference between the two tiers.