Install Benson on WooCommerce

The Benson for WooCommerce plugin is the way to install Benson on WooCommerce. It's free in the WordPress.org plugin directory, so you install it from your WordPress admin like any other plugin. It adds the Benson script to every page, sends your paid orders so you can see which came from coupon-extension sessions, and lets WooCommerce check codes against your checkout rules.

Install the plugin#

Get it on WordPress.orgDownload the zip

1. In WordPress, go to Plugins → Add New Plugin, search for Benson for WooCommerce, then click Install Now and Activate.
2. Open WooCommerce → Benson and click Connect to Benson, then connect this store. The plugin gets its keys from Benson: nothing to copy.

WooCommerce has to be active. Connect to Benson opens Benson: create your free account or sign in, check the store and click Connect (a store that isn't in Benson yet is added as you connect). You're back in WordPress, connected. The plugin has your site key and a policy key, so Benson is on every page, and order attribution, coupon sync, the store audit and checkout rules are on. Status on the same page shows that Benson knows your store.

Connect to Benson arrived in plugin 1.5. It needs the store and its WordPress admin on one https address, like https://yourstore.com; a store in a subdirectory, on another port or on plain http pastes its keys. You can always paste keys: open Have your keys? Paste them instead on the same page, and paste your site key (it starts with pk_live_; it's under Settings → Install in Benson) and a policy key (create it under Protection → Checkout rules → Install; it's shown once). The site key alone adds Benson to every page; the policy key turns on the rest.

The plugin needs WordPress 6.5 or later, PHP 8.1 or later and WooCommerce 8.0 or later, and works with the classic checkout and the Cart and Checkout blocks. Can't install from the directory? Download the zip above (or from Protection → Checkout rules in your dashboard) and upload it under Plugins → Add New Plugin → Upload Plugin.

Check it's live#

Open your store in a normal browser tab. The setup wizard shows Verified: Benson is live within a few seconds. If it doesn't, see Troubleshooting.

What the plugin does#

• Adds the Benson script to every page, checkout included, loaded asynchronously so it never blocks rendering. Benson's script runs on your checkout page too, so your blocker rules apply there.
• Links orders to sessions and sends paid orders to Benson, so the dashboard shows revenue, conversion and discount depth with and without an extension. See Order attribution.
• Checks codes at checkout. In a session where Benson saw a coupon extension, WooCommerce asks Benson before it accepts a code and refuses one your checkout rules don't allow, with your message. Shoppers without an extension are never affected, coupons you add to an order in wp-admin are never checked, and if Benson doesn't answer within a second the coupon is judged by WooCommerce alone.
• Syncs your coupons (optional, on by default) so they fill your allowlist: code, discount, minimum spend, expiry, and whether it's restricted to customer emails.
• Sends a daily coupon usage summary for your store audit: 30-day totals only.
• Works with the discount widget: it gives the widget your cart and applies the codes it offers through WooCommerce, which validates them as usual.
• Counts AI crawlers (from plugin 1.3): storefront requests from AI bots such as GPTBot, ClaudeBot and PerplexityBot are reported to Benson with the page path, so the AI & agents page shows what they read. These bots don't run JavaScript, so only your server sees them. See AI referrals, crawlers and agents.
• Follows the WP Consent API when your consent plugin supports it (see Consent).

Background jobs run on Action Scheduler, under WooCommerce → Status → Scheduled Actions in the benson group.

Order attribution#

When a shopper's consent allows Benson to keep a session, the plugin stores the Benson session id and the coupon extensions detected in it on the order as it's placed, through the classic checkout or the checkout block. It reads them from a first-party cookie, bn_wc, that the plugin writes next to the Benson script (listed with the rest in Consent and storage).

• Paid orders (every status WooCommerce counts as paid) are sent to Benson in the background, and again if they're later cancelled or refunded, which takes them out of your totals.
• Once a day, recent orders Benson doesn't have as they are now are sent again. The first run after the store connects covers the last 30 days, so your Orders page starts with history. Those older orders weren't placed with Benson on the page, so they show as not linked to a session.
• What's sent: the order id and number, dates, currency, amounts, coupon codes with their discounts, the Benson session id, the detected extension ids, whether it's a test order, and (from plugin 1.3.1) the referrer's host and utm_source from WooCommerce's own order attribution, so AI orders count even when the visit wasn't tracked. Never the full referrer URL, names, emails, phone numbers or addresses.
• Test orders: orders on a site whose WordPress environment isn't production (local, development or staging), and WooPayments test-mode payments, are marked as test orders.
• Orders without consent, or placed without a storefront visit, arrive without a session and count as unlinked on the Orders page's coverage card. Orders created in wp-admin or through the REST API are counted as orders from outside the online store.

To stop sending orders, turn off Send orders to Benson under WooCommerce → Benson.

Consent#

Benson follows the consent mode you choose under Settings → Tracking. Without consent it keeps no visitor id and writes no cookies, so orders aren't linked to a session.

If your consent plugin supports the WP Consent API (many WordPress consent plugins do), the plugin passes the shopper's choice for the statistics category to Benson with Benson.consent() on every page and whenever it changes:

• In Manual mode, that's the call Benson waits for.
• In Auto mode, the plugin also tells Benson to wait for that answer before it stores anything.
• In TCF, Google Consent Mode and None, Benson reads its own signal and the plugin stays out of it.

Cache and optimisation plugins#

Delaying JavaScript until the shopper interacts would let coupon extensions act before Benson loads. The plugin excludes benson.js and its inline lines from delaying, deferring, combining and minifying in WP Rocket, LiteSpeed Cache, Autoptimize, SiteGround Optimizer, W3 Total Cache and Perfmatters. With another optimiser, exclude benson.js and bensonWoo from its JavaScript settings.

Settings#

• Keys and settings (under the connection): your site key and policy key, and Connect again to move the store to another Benson account. Connecting again gives the plugin new keys; the old policy key keeps working for 24 hours.
• Server API URL (optional): only if your server must reach Benson at a different address than browsers do. The BENSON_SERVER_API_URL constant in wp-config.php wins over the field.
• Sync coupons to Benson and Send orders to Benson: on by default.

Developer hooks#

// Log every refusal.
add_action( 'benson_coupon_denied', function ( $code, $result, $tag ) {
	error_log( 'Benson refused ' . $code . ': ' . ( $result['reason'] ?? '' ) );
}, 10, 3 );

// Keep wholesale orders out of Benson.
add_filter( 'benson_order_payload', function ( $payload, $order ) {
	return $order->get_meta( '_wholesale_order' ) ? false : $payload;
}, 10, 2 );

Add the snippet instead#

If you can't install plugins, add the snippet yourself. It adds Benson to every page, but order attribution and checkout rules need the plugin. Your snippet, with your site key, is in the setup wizard and under Settings → Install:

<script async src="https://cdn.trybenson.com/benson.js" data-site="pk_live_YOUR_SITE_KEY"></script>

1. In WordPress, open Code Snippets → Add Snippet (WPCode) and create a Header snippet.
2. Paste the snippet, set the location to Site Wide Header, and save it active.
3. No snippet plugin? Paste it into your theme's header.php, right before </head>.