The pipeline at a glance
When /v1/analyze receives an order it runs four scorers — three deterministic, one AI — then merges them into a final risk score from 0 to 100.
- Rules engine — your store-defined conditions.
- Heuristic scorer — deterministic signals (AVS, CVV, address mismatch, amount, etc.).
- History analyzer — customer and IP history for this merchant.
- AI reasoning — a calibrated LLM call, on paid tiers.
Final-score weights
With AI enabled (paid tiers):
final = 0.40 × rules + 0.25 × heuristic + 0.20 × history + 0.15 × aiWithout AI (Shadow tier or LLM disabled):
final = 0.50 × rules + 0.30 × heuristic + 0.20 × historyWeights are env-tunable per deployment. Defaults shipped above.
Risk bands
| Score | Risk level | Default action |
|---|---|---|
| 0–30 | low | approve |
| 31–50 | medium | review |
| 51–75 | high | review (or hold) |
| 76–100 | critical | hold / reject |
Band boundaries are merchant-configurable in Settings → Thresholds.
Heuristic signals
All additive, clamped to 0–100. Selected highlights:
- AVS: match 0; partial +12; mismatch +30; unavailable +4; missing +5.
- CVV: match 0; mismatch +25; unavailable +3; missing +4.
- Amount: >$1000 +15; >$500 +8; >$200 +3.
- Ship/bill mismatch: country +15; city+postal +6.
- Email: missing +10; absurdly long local part +5.
- Address: incomplete +5; PO Box +3; missing +8.
- Guest checkout: +5. Coupon stacking >2: +3.
Customer history
The history scorer queries this merchant's past orders by email (hashed) and IP, looking for prior chargebacks, repeat purchases, account age, and review-decision outcomes. Results are cached in Redis for 10 minutes.
AI reasoning
On paid tiers, every order is also evaluated by a Claude-family model that sees the full order context — addresses, payment signals, history summary, and rule firings. It returns a calibrated risk band and a natural-language explanation that gets stored with the order for audit. The AI is fully managed — no separate API key, no token passthrough.
Shadow mode
When shadow_mode_enabled is set on a store, the deterministic scorers run but the LLM is skipped and side effects (Shopify Order Risk writeback, WooCommerce action hooks) are suppressed. The dashboard's Run AI Analysis button forces the AI scorer on a single order regardless of shadow mode.
Auto-approve override
If confidence is above the auto-approve threshold and the risk level is medium or high, the score is downgraded to approve. This is how we cut review queue noise without compromising on critical-band orders.