Checkout Enforcement
4 min read
Checkout enforcement is the runtime layer that prevents blocked customers from completing checkout. It works on both Classic shortcode-based checkout and WooCommerce Blocks / Store API checkout through a single unified mechanism — the TrustLens Request Gate. This page explains how enforcement works, when it kicks in, and how to configure it.
The Master Toggle #
Checkout enforcement is gated by a single master toggle: Settings → General → Enable checkout blocking. By default this is off in Free.
When the toggle is off:
- Customers can be marked as blocked, but the block has no checkout-side effect
- Their orders proceed normally
- You see the block state in admin but customers don’t experience friction
When the toggle is on:
- Blocked customers cannot add to cart or complete checkout
- The block is enforced via the Request Gate
- Customers see a generic error message
The toggle exists so you can observe scoring for weeks, build confidence in the signals, and only enable enforcement once you’re sure the blocks are correct. Once enabled, leaving it on is the default.
The Request Gate #
The Request Gate is TrustLens’s unified checkout interception layer. A single rule-registration surface intercepts both Classic and Blocks / Store API checkout requests.
At a high level:
- Checkout request arrives (Classic POST or Store API endpoint)
- The Gate runs all registered rules in order:
- Card-Testing velocity / lockout / Panic Freeze
- Blocked-customer check
- Pro: automation-rule actions that act at checkout
- Any rule can reject the request
- If all rules pass, the request proceeds to WooCommerce’s checkout processing
The single-surface design means rule logic only has to be written once — it automatically works on both checkout types. This is a key compatibility win, since maintaining separate Classic and Blocks integrations is a common source of plugin bugs.
What “Blocked Customer” Means at the Gate #
When a checkout request arrives, the Gate:
- Extracts the billing email from the request
- Hashes it
- Looks up the customer record
- Checks
is_blockedflag - If blocked, rejects the request with a generic error
The lookup is fast — a single indexed query on the email hash. There’s no measurable performance impact on legitimate checkout requests.
What the Customer Sees #
The blocked customer sees a generic error message. By default:
“We’re unable to process your order at this time. Please contact support.”
The wording is deliberately non-specific. It doesn’t reveal that they’ve been blocked or what triggered the block. This prevents adversarial probing — a bad actor who knows the block message can attempt variations to figure out what they need to change.
The message is customizable in Settings → General → Block message. Keep it neutral; don’t include words like “blocked,” “fraud,” or “risk.”
Classic vs Blocks Checkout #
The Gate runs identically for both:
- Classic checkout — POST to the checkout endpoint. The Gate intercepts the POST and returns an error notice that displays in the WooCommerce notice area.
- Blocks checkout — Store API requests (e.g.
/wc/store/checkout). The Gate returns a JSON error that the Blocks frontend renders as an error message.
From the customer’s perspective, both look like a generic checkout error. From the developer’s perspective, both go through the same rule engine.
Add-to-Cart Blocking #
By default, blocked customers can browse and add to cart — the block only enforces at checkout. To also block add-to-cart for blocked customers: Settings → General → Block add-to-cart for blocked customers.
When enabled, the Gate also intercepts add-to-cart requests. This is more aggressive — it makes the block visible earlier in the customer journey — but it can also produce more confusion for customers who might genuinely not understand why they can’t add items.
The default is checkout-only enforcement, which is the gentlest visible block.
API Orders #
Orders created via the WooCommerce REST API (custom integrations, admin tools) bypass the Request Gate by default. The Gate is for customer-facing checkout flows; admin-initiated orders go through different code paths.
If you have a custom integration that creates orders on behalf of customers and you want it to respect the block list, hook into woocommerce_checkout_order_processed and check the customer’s is_blocked flag yourself.
Subscription Renewals #
WooCommerce Subscriptions renewals are processed via Action Scheduler, not the standard checkout flow. They don’t go through the Request Gate by default.
To enforce blocks on subscription renewals: hook into wcs_renewal_order_created and call wstl_is_blocked() on the customer. If blocked, fail the renewal and notify the admin.
There’s no built-in subscription enforcement in Free; Pro automation rules can be configured to act on subscription renewal events.
Edge Cases #
- Guest checkout with no email at the Gate. If the email isn’t available yet (cart page before email entry), the Gate can’t check blocks. Enforcement kicks in once the email is submitted.
- Email typos. A blocked customer entering a typo email at checkout might bypass the block. This is a known limitation — blocks are email-keyed.
- Multi-email customers. If the customer uses a different email than the one they’re blocked under, the Gate doesn’t connect them. Linked-accounts detection can sometimes catch this, but enforcement is per-customer.
Audit Log #
Every blocked-checkout attempt is logged with:
- Timestamp
- Customer email hash
- Customer’s current trust score and segment
- Reason for block (e.g. “Manual block by [email protected] on 2024-03-15”)
- Source of the attempt (Classic / Blocks)
The log is visible per-customer in the event timeline and as an aggregate on the Notifications / Reports tab.
Email Alert on Block #
When the master toggle is on and a blocked customer attempts checkout, TrustLens fires the Blocked Checkout Alert (a built-in Free notification). The admin email receives a notification with the customer’s email, score, and attempt timestamp.
This is useful for:
- Knowing when blocked customers are still trying — they might escalate to a support email
- Verifying enforcement is working
- Catching false positives quickly
The alert can be disabled or routed to a different email in Settings → Notifications.
