Checkout Enforcement

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 → Blocking Settings → Enable Blocking (“Allow blocking customers from checkout”). By default this is off.

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 complete checkout or pay for an existing order
• Logged-in blocked customers are also refused by classic add-to-cart buttons, and Blocks cart updates that carry their billing email are refused
• The block is enforced via the Request Gate
• Customers see a generic error message

Allowlisted customers are never blocked at checkout, and neither is anyone logged in as a store admin or shop manager (users with the manage_woocommerce capability) — so test enforcement while logged out.

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:

1. A request arrives: a Classic checkout POST, a Store API checkout or cart write (/wc/store/v1/checkout, /wc/store/v1/cart/…), a classic add-to-cart, or a pay-for-order submission
2. Store admins pass straight through; Pro allowlisted fingerprints and IP ranges (Card-Testing Defense) bypass the rules
3. The Gate runs all registered rules in order:
   • Browser challenge (when enabled in Card-Testing Defense)
   • Card-Testing velocity / lockout / Panic Freeze
   • Blocked-customer check (only registered when Enable Blocking is on)
4. The first rule that rejects the request wins
5. If all rules pass, the request proceeds to WooCommerce’s checkout processing

Automation rules aren’t Gate rules — they run on events such as Order Placed, after the request is accepted.

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:

1. Takes the billing email from the request (for pay-for-order, from the order; for classic add-to-cart, from the logged-in account)
2. Hashes it
3. Looks up the customer record
4. Skips allowlisted customers, then checks the is_blocked flag
5. If blocked, rejects the request with a generic error and logs a checkout_blocked event

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 are unable to process your order at this time. Please contact support for assistance.”

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 (/wc/store/v1/checkout and cart writes). The Gate returns a JSON error (HTTP 403, code email_blocked) that the Blocks frontend renders as an error message.
• Pay for order — the /checkout/order-pay/ page. The Gate adds an error notice so the payment isn’t attempted.

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 #

There’s no separate add-to-cart setting. When Enable Blocking is on, the Gate also checks add-to-cart requests, but it can only block when it knows the email: a logged-in blocked customer is refused by classic add-to-cart buttons (their account email is used), and Blocks cart updates are refused once they carry the billing email. Guests can usually fill their cart and are stopped at checkout, once they enter their email.

---

API Orders #

Orders created via the WooCommerce REST API (custom integrations, admin tools) bypass the Request Gate. 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, call wstl_is_blocked( $email ) in your integration before creating the order and refuse if it returns true.

---

Subscription Renewals #

WooCommerce Subscriptions renewals are processed via Action Scheduler, not the standard checkout flow. They don’t go through the Request Gate.

To enforce blocks on subscription renewals: hook into wcs_renewal_order_created and call wstl_is_blocked() on the customer’s email. If blocked, fail the renewal and notify the admin.

There’s no built-in subscription enforcement, in Free or Pro — automation rules have no renewal trigger, and renewal orders don’t fire Order Placed.

---

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 as a checkout_blocked event with:

• Timestamp
• Customer email hash and email
• IP address
• Source of the attempt (the checkout route)

The event is visible per-customer in Recent activity on the profile. Blocked attempts are also counted in the weekly summary email, and Pro scheduled reports can include a Blocked Checkout Attempts section.

---

Email Alert on Block #

When a blocked customer attempts checkout, TrustLens can send the Blocked Checkout Alert (a built-in Free notification) to your notification email. It includes the customer’s email, trust score, segment, return rate and total refunded, with a link to their profile. The same alert fires when Card-Testing Defense first locks out a device whose checkout carried an email.

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 needs both Enable Notifications (off by default) and the Blocked Checkout Alert toggle (on by default) under Settings → Alerts & Reports → Notifications, where you also set the Notification Email.