--- title: Category Aware Risk description: "The Category-Aware Risk module (shown in Settings as **Product Risk Intelligence**) catches a pattern most fraud-detection systems miss: return behavior means something different depending on *what* is being returned. A high return rate on apparel is often just sizing; the…" url: "https://webstepper.io/docs/trustlens/detection-modules/category-aware-risk/" updated: "2026-10-18" category: Detection Modules --- # Category Aware Risk The Category-Aware Risk module (shown in Settings as **Product Risk Intelligence**) catches a pattern most fraud-detection systems miss: return behavior means something different depending on *what* is being returned. A high return rate on apparel is often just sizing; the same rate on serial-numbered electronics or low-resale items is a different story. Rather than adding a second penalty on top of return abuse, the module tells the Returns module how much weight each customer's returns deserve. Module ID: `categories`. Default: enabled. Free tier (complete). --- ## What It Observes The module hooks into order placement and refund events (including edited and deleted refunds). For each event the module: 1. Iterates over the line items of the order or refund 2. Records a product fact per line item in `{prefix}trustlens_product_facts`: product and SKU, its WooCommerce categories, order value, refunded value and quantity, and — where your store provides them — cost of goods, resale value and whether the item is serial-controlled 3. Updates per-category counters in `{prefix}trustlens_category_stats`: orders containing the category, refunds containing the category (once per order), and refund value attributable to the category 4. Keeps refund value that WooCommerce can't map to a line item in a separate "unattributed" bucket Product facts are read from your products: cost of goods from common COGS meta keys (`_trustlens_cogs`, `_wc_cog_cost` and similar), resale value from `_trustlens_resale_value`, and serial control from `_trustlens_serial_required`. Integrations can adjust the stored facts with the `trustlens/product_risk_fact` filter. --- ## What It Signals The module emits **no signal of its own** — it never adds a separate penalty, so a return is never punished twice. Instead it produces a **product-risk multiplier** that the Returns signal is scaled by, from 0.5× (returns weigh half as much) to 2× (returns weigh double). With default settings and no special product facts, the multiplier is 1.0× for every category. When the multiplier differs from 1.0, the Returns reason text says so, for example *"Product risk multiplier: 1.25× — high SKU return rate"*. --- ## The Weight System Category weights are how you tell TrustLens which categories matter most. Every category starts at **1.00× — Normal**; there are no built-in category defaults. To make returns in a category count for more, raise its weight; to make them count for less, lower it. Configure weights in **Settings → Refunds → Product Risk by Category**. The screen lists your WooCommerce product categories (plus a **Default / uncategorized** row) with a dropdown each: | Option | Multiplier | | --- | --- | | Low | 0.50× | | Reduced | 0.75× | | Normal (default) | 1.00× | | Elevated | 1.25× | | High | 1.50× | | Critical | 2.00× | The Default / uncategorized row is used for products with no category. When a product sits in several categories, the highest weight applies. ### Why Weights Matter Set Shoes to 0.75× and Luxury to 1.50×, and the same pattern of returns costs a shoe buyer half as many points as a luxury buyer. Without weights, TrustLens would treat both identically and over-flag shoe-buying customers while under-flagging luxury returners. ### How to Pick Weights The recommended approach: look at your store-wide return rate per category. Categories where the store-wide rate is significantly above your overall average should get weights < 1.0 (because elevated rates there are normal). Categories where the store-wide rate is below average and items are high-value should get weights > 1.0 (because elevated rates there are unusual *and* expensive). --- ## Settings | Setting | Default | Description | | --- | --- | --- | | **Product Risk by Category** | 1.00× for every category | Per-category multiplier, 0.50×–2.00× (Settings → Refunds) | | **Module enabled** | On | Master toggle (the Product Risk Intelligence card in Settings → Detection) | The Product Risk Intelligence card on the Detection tab shows how many categories you've customized and links to the Refunds screen. With many categories, a filter box helps you find the one you want. --- ## Common Patterns ### The Category-Specific Wardrober **Signature:** Customer has 8 orders, 4 refunds. All 4 refunds are from "Cocktail Dresses," which you've set to 1.50× — High. **Signals:** One Returns signal: the 50% rate earns its tier points (plus any wardrobing evidence), and the total is multiplied by 1.5 before the -50 cap. **Profile:** Risk or Critical. The multiplier line in the reason text shows the category weighting. ### The Defective Product Cluster **Signature:** Many different customers return the same product. The SKU's own return rate climbs. **Detection:** A SKU with a return rate of 50%+ across 3+ orders adds +0.15 to the multiplier of every customer who returned it (+0.08 at 30%+), so those customers' Returns signals are weighted up. **Action:** Investigate the SKU. Don't penalize customers for legitimate returns of defective items — lower the category's weight temporarily until the underlying issue is fixed. ### The High-Value Item Returner **Signature:** Customer with a moderate overall return rate but all returns concentrated in a high-priced category. **Detection:** If you've set a higher weight for that category, the Returns signal hits harder than the overall return rate alone would. **Profile:** Caution to Risk depending on the magnitude. --- ## How the Calculation Works Step by step for a single customer, each time the Returns signal is calculated: 1. Read the customer's refunded product facts 2. For each refunded item, start from its category weight (the highest of its categories, or the Default weight) 3. Add product adjustments: for a SKU with 3+ orders store-wide, +0.15 if its return rate is 50%+ (+0.08 at 30%+) and +0.10 if 10%+ of its orders were disputed; for any item, +0.08 if it is serial-controlled and +0.07 when its resale value is under 40% of its price 4. Clamp each item's factor to 0.5–2.0 5. Average the factors, weighted by each item's refunded value; unattributed refund value counts at the neutral 1.0 6. Clamp the result to 0.5–2.0 and multiply the Returns raw points by it Because the average is weighted by refund value, an expensive return in a high-weight category moves the multiplier more than a cheap one. --- ## Where to See Category Data There is no category card on the Dashboard. Category and product context shows up in each customer's Returns reason text (the multiplier line and the factors behind it), and a customer's per-category stats are included in their WordPress personal-data export. Use your WooCommerce reports and the Product Risk by Category screen to distinguish customer-side abuse from product-side issues. If a single category has a 40% store-wide return rate, the issue isn't your customers — it's the products. Fix the products (or lower the weight) before blocking the customers. --- ## False-Positive Watch List - **Wide categories with mixed product quality.** A category like "All Sale Items" lumps together products with very different return profiles. Use more specific categories where possible. - **Recently-restocked categories with bad batches.** A defective batch can spike returns for a few weeks. Tune the weight down temporarily. - **Products in several categories.** The highest weight wins, so a product that is in both "Sale" and "Luxury" is weighted as Luxury. - **Mis-categorized products.** If product taxonomy is messy, weights apply to the wrong items. Audit the WooCommerce category tree before tuning weights. --- ## Disabling the Module Reasonable to disable if your store has a single product category or your category taxonomy is too messy to weight meaningfully. When disabled, the multiplier is a neutral 1.0× for everyone, so the Returns signal is unaffected by category or product context; new product facts and per-category stats stop updating, and the existing tables are preserved. --- ## Reading the Categories Section of a Profile - **Signal breakdown** — there is no separate Categories row; look in the Returns reason text for the "Product risk multiplier" line and its drivers (high SKU return rate, chargeback-exposed SKU, serial-controlled merchandise, low resale recovery) - **Event timeline** shows `category_refund` events with the refunded amount per category --- ## Interaction with the Returns Module Categories and Returns are designed to work as one, not to duplicate each other: - Returns measures *how much* a customer returns — rate, value and patterns, judged against your store baseline - Categories decides *how much that matters* given what was returned A customer is only ever penalized through the Returns signal; Categories can raise or lower that penalty but never adds one of its own. Together, the two produce a clearer picture than either alone: Returns tells you the magnitude, Categories tells you the context.