Benson for WooCommerce

توضیحات

Benson measures how coupon and cashback browser extensions (Honey, Capital One Shopping, Rakuten and others) affect your store. This plugin connects WooCommerce to your Benson account:

• Adds the Benson script to every page, checkout included. It loads asynchronously, so it never blocks rendering, and it is kept out of cache plugins’ “delay JavaScript” and combine settings so it runs on time. The Benson blocker rules you set up in the dashboard apply on the checkout page too.
• Attributes your orders. When a shopper’s consent allows it, the plugin records the Benson session, the coupon extensions detected in it, the tools Benson loaded in it and any holdout it was part of on the order. Paid orders are then sent to Benson (amounts, codes, the session; never customer details), so your dashboard shows revenue, conversion and discount depth for shoppers with and without an extension. Cancelled and refunded orders are updated, and a daily check catches anything missed.
• Applies your strict code policy on the server. When the Benson script has detected a coupon extension in a shopper’s browser, it stores a signed note in a first-party cookie (bn_ext), which the plugin also keeps in the shopper’s WooCommerce session. When a coupon is applied in such a session, the plugin asks Benson whether the code is on your extension allowlist. If it isn’t, WooCommerce rejects the coupon with the message you wrote in Benson. Shoppers without an extension are never affected, and coupons you add to an order in wp-admin are never checked.
• Applies your partner code locks (beta). When you lock a partner’s code in Benson, the Benson script notes which partner sent the shopper in a first-party cookie (bn_aff, only with consent). When a locked code is applied, the plugin asks Benson whether it applies in this session: it does for the shoppers that partner sent, and not when another partner sent the session or a coupon extension is active in it. Other coupons are never checked: the plugin reads which codes are locked (as hashes) from your site’s public config, at most every five minutes.
• Fails open. If Benson doesn’t answer within one second, or answers with an error, the coupon is judged by WooCommerce alone, as if the plugin weren’t there.
• Syncs your coupon codes (optional, on by default) so they appear in your Benson allowlist: code, discount type and amount, minimum spend, expiry, and whether the coupon is restricted to specific customer emails. No customer or order data is sent.
• Sends a daily coupon usage summary for your Benson store audit: over the last 30 days of paid orders, the order count, revenue, how many orders used a coupon, and per coupon code the number of orders and the total discount. Only totals are sent.
• Works with the discount widget. On shop, product, cart and checkout pages it gives Benson’s widget your cart (from the WooCommerce Store API) and applies the codes it offers, with WooCommerce validating them as usual.
• Counts AI crawlers. AI crawlers and fetchers (GPTBot, ClaudeBot, PerplexityBot, ChatGPT-User and others) don’t run JavaScript, so only your server sees them. When one requests a storefront page, the plugin tells Benson which bot (by user agent), the page path and the response status, so your dashboard shows which pages AI reads. It never waits for the answer.
• Follows the WP Consent API. With a consent plugin that supports it, Benson’s cookies and storage follow the shopper’s choice for the “statistics” category, and tools that need “marketing” or “preferences” consent load only when the shopper gave it.

Background jobs run on Action Scheduler (WooCommerce → Status → Scheduled Actions, group benson). The settings page shows the connection, the last heartbeat, coupon sync and order push, and the last error.

What it can’t do: the extension cookie only exists once the Benson script has seen an extension in that browser, so a code entered before detection (or with cookies disabled or not consented to) is judged by WooCommerce alone. Orders placed without consent arrive unlinked.

External services

This plugin connects the store to Benson (https://trybenson.com), the service it is built for, at the API URL you set (by default https://api.trybenson.com). It sends:

• Connect to Benson. Only when you click “Connect to Benson” on the settings page: your browser goes to /api/woocommerce/connect/start with the store’s address, name, currency and time zone, the address of the page to come back to, and a hash of a one-time secret the plugin keeps. Once you connect the store in Benson, your server sends the one-time code Benson returned, with that secret, to /api/woocommerce/connect/exchange and receives the site key, a policy key, the store’s name in Benson and its dashboard address.
• The Benson script and its config. Every storefront page loads benson.js from the API URL, which then reads your site’s public config from /v1/c/<site key>. The script runs in the shopper’s browser and follows the consent mode you set in Benson.
• The connection check. When your keys are saved, once a day, and when you click “Check connection”, the server reads /v1/c/<site key> and sends your site key to /v1/policy/heartbeat, so Benson can show the plugin is installed. On sites with partner code locks, the server also reads /v1/c/<site key> at most every five minutes when a coupon is applied, for the hashed list of locked codes.
• The policy check. When a coupon is applied in a session with a bn_ext note, the server sends your site key, the note (a session id, extension ids, an expiry and a signature) and the coupon code to /v1/policy/check. When a locked partner code is applied, it also sends the session’s partner from bn_aff (a network and partner id, or - for none), the Benson session id and the extension ids detected in the session.
• Coupon sync (optional). When coupons change and once a day, the server sends your coupon codes and their discount settings to /api/sites/<site key>/discount-codes/import, authenticated with your policy key.
• The usage summary. On activation, when your keys are saved, and once a day, the server sends the 30-day coupon usage summary (totals only) to /api/sites/<site key>/discount-codes/usage-summary, authenticated with your policy key.
• AI crawler hits. When a storefront page is requested by a known AI crawler or fetcher (matched by user agent), the server sends your site key, the bot’s user agent, the page path (no query string), the time and the response status to /v1/f, without waiting for an answer. Requests from people are never sent. The benson_ai_fetch_enabled filter turns it off.
• Orders (optional). When an order is paid, cancelled or refunded, and once a day for recent orders, the server sends the order’s id and number, dates, currency, amounts, coupon codes with their discounts, the Benson session id, detected extension ids, the keys of the tools Benson loaded, the session’s experiment and holdout assignments, the referrer’s host and utm_source from WooCommerce’s order attribution (never the referrer URL) and whether it’s a test order to /api/sites/<site key>/orders/import, authenticated with your policy key. No customer details are sent.

Benson’s terms of service: https://trybenson.com/legal/terms
Benson’s privacy policy: https://trybenson.com/legal/privacy

Developer hooks

• benson_coupon_denied (action, $code, $result, $tag): a coupon was refused by the policy, just before WooCommerce shows the message.
• benson_policy_check_result (filter, $result, $code, $tag): Benson’s answer before WooCommerce acts on it. null means Benson didn’t answer (allowed). Return array( 'allow' => true ) or array( 'allow' => false, 'message' => '…' ).
• benson_loader_attributes (filter, $attrs): attributes on the benson.js tag, e.g. data-consent => required. true prints a bare attribute, false removes one.
• benson_coupon_sync_limit (filter, $limit): coupons per sync, newest first (1 to 5,000; default 5,000).
• benson_order_payload (filter, $payload, $order): the order Benson receives. Return false to skip the order. Only the documented fields are sent.
• benson_ai_fetch_enabled (filter, $enabled, $ua): whether to report this AI crawler request to Benson (default true).