Smart Bundle Engine — Documentation

Overview

Smart Bundle Engine analyses your WooCommerce order history to detect products actually purchased together, automatically generates the matching bundles and displays them on the product page, in the cart and in the post-purchase email — with margin control that automatically caps the discount when needed.

Installation

1. Download df-smart-bundle.zip from your DataFirefly customer account.
2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Select the ZIP, click Install Now, then activate the plugin.
4. A new Smart Bundles menu appears in the admin sidebar.

On activation, the plugin creates 4 dedicated tables (df_sbe_cooccurrence, df_sbe_bundles, df_sbe_bundle_items, df_sbe_analysis_state) and schedules the analysis cron.

Quick start

1. Go to Smart Bundles → Analysis and click Run analysis now.
2. Once the analysis is done, the Top purchase affinities table shows the detected pairs with their metrics (occurrences, confidence, lift).
3. If auto-generation is enabled (default), bundles are created automatically — review them under Smart Bundles → Bundles.
4. Visit a relevant product page on the storefront: the “Frequently bought together” block appears below the product summary.

Co-occurrence analysis

The engine processes completed and processing orders within the configured analysis window (180 days by default), in batches of 200 orders. For each order containing multiple products, all pairs are extracted and counted.

The three metrics

• Occurrences — number of orders containing the A+B pair.
• Confidence — P(B|A) as a percentage: in what share of orders containing A do we also find B. A confidence of 20 means B appears in 20% of orders containing A.
• Lift — ratio between the observed pair frequency and the expected frequency if A and B were independent. A lift above 1 indicates a real affinity; above 2, a strong one.

Scheduling

The analysis runs automatically via WP-Cron (hook df_sbe_run_analysis). Each run processes up to 25 batches of 200 orders, then resumes on the next trigger thanks to a persistent cursor — no order is ever processed twice. The Reset state button empties the analysis tables and starts over.

Automatic bundle generation

After each complete analysis, the engine selects pairs that pass your thresholds and creates the matching bundles. Three settings control the selection:

• Minimum co-occurrences (3 by default) — minimum number of orders containing the pair.
• Minimum confidence (10% by default) — confidence threshold below which the pair is ignored.
• Max bundles per product (3 by default) — prevents over-saturating a single product.

Selected pairs are ranked by score (lift × occurrences). Auto-created bundles are tagged with the “Auto” origin; existing bundles with the same products are never duplicated. Manual bundles are always preserved across re-analyses.

Managing bundles

The Smart Bundles → Bundles screen lists all bundles with their products, discount, minimum margin, display contexts, views and conversions. You can filter by status, origin (auto/manual) or free-text search.

Creating or editing a bundle

1. Click New bundle or Edit on an existing bundle.
2. Search and add the products (minimum 2) — each item’s quantity is adjustable and the order can be rearranged by drag and drop.
3. Set the discount (percentage or fixed amount) and the minimum margin.
4. Tick the desired display contexts: product page, cart, email.
5. The priority determines display order when several bundles are eligible (higher = first).

On an existing bundle, a Pricing preview table shows the live subtotal, estimated cost, requested vs applied discount, final price and actual margin.

Margin control

Each bundle has a minimum margin threshold (as % of the final price). The engine computes the corresponding floor price:

min_final_price = total_cost / (1 − min_margin / 100)

If the requested discount would push the final price below this floor, it is automatically capped to the maximum compatible discount. The discount shown on the storefront is therefore always safe.

Cost source

Each product’s cost is determined in this order:

1. Product meta — the _df_cost_price key by default, configurable in the settings (compatible with Cost of Goods and other cost-price plugins).
2. Fallback ratio — for products without a cost, a percentage of the sale price is assumed (50% by default).

Storefront display

Product page

The block hooks into woocommerce_after_single_product_summary with a configurable priority (15 by default, just before related products). It shows the product thumbnails connected by “+” signs, the struck-through subtotal, the bundle price and the one-click add-to-cart button.

Cart

Suggestions appear below the cart table (woocommerce_after_cart_table). Bundles whose products are all already in the cart are automatically hidden.

Post-purchase email

A suggestion block is inserted into the Completed order and Processing order emails (customer-facing only), in HTML and plain-text variants, with a direct return link to the shop.

Each context can be toggled independently and its title customised in the settings.

Discount application

The plugin never alters product prices. When a bundle is added to the cart, each item carries an internal marker; as soon as all bundle items are present, the discount is applied as a WooCommerce negative fee (“Bundle discount”). This approach:

• preserves line prices and sales reports;
• stays compatible with taxes, shipping and coupon codes;
• automatically removes the discount if a bundle item is removed from the cart.

Performance tracking

Each bundle display increments its views counter; each order containing a complete bundle increments its conversions (on transition to “processing” or “completed” status, with a guard against double counting). The per-bundle conversion rate is displayed in the bundle list, and the Analysis screen shows the global statistics: orders analysed, pairs detected, active bundles, cumulative views and conversions.

Settings reference

Co-occurrence analysis

• Analysis window (days) — 180 by default. Completed and processing orders within this period.
• Minimum co-occurrences — 3 by default.
• Minimum confidence (%) — 10 by default.
• Automatic bundle generation — enabled by default.
• Max bundles per product — 3 by default.

Pricing & margin

• Default discount (%) — 10, applied to auto-generated bundles.
• Default minimum margin (%) — 20.
• Cost price meta key — _df_cost_price.
• Fallback cost ratio (%) — 50.

Display

• Contexts — product page / cart / email, toggleable separately.
• Product page hook priority — 15 by default.
• Titles — one customisable title per context.

Multilingual

The plugin ships with 5 languages (FR, EN, ES, DE, IT) as .po/.mo files plus a .pot file for your own translations (textdomain df-smart-bundle). Compatible with Polylang and WPML — the displayed language follows the site or user locale.

Uninstall

Deactivating the plugin simply removes the scheduled cron — your data is preserved. Deleting the plugin (via Plugins → Delete) runs uninstall.php, which permanently removes the 4 tables, all options and the order metadata created by the plugin (HPOS-aware).

Troubleshooting

No bundles are generated

• Check that the analysis has run: Smart Bundles → Analysis must show a non-zero number of analysed orders.
• Lower the thresholds (minimum co-occurrences, minimum confidence) if your history is small.
• Check that auto-generation is enabled in the settings.

The bundle doesn’t show on the storefront

• The bundle must be active and the relevant context ticked.
• A bundle whose computed discount is zero (fully capped by margin) is hidden on the product page.
• In the cart, a bundle that is already complete is hidden by design.
• Purge your page cache if you use a caching plugin.

The applied discount is lower than configured

That’s margin capping at work: the bundle’s total cost doesn’t allow the requested discount without breaching the minimum margin. Check the product costs or adjust the bundle’s margin threshold.

FAQ

Does the plugin work with variable products?

The analysis and bundles operate at parent-product level. Variations of the same product are counted together.

Can I exclude some products from the analysis?

Not in version 1.0.0 — simply delete or deactivate the unwanted bundles; they won’t be recreated if you delete them after disabling auto-generation.

Are bundles compatible with coupon codes?

Yes. The bundle discount is a negative fee independent of WooCommerce coupons; the two stack.

What is the performance impact?

The analysis runs in the background in batches. On the storefront, bundle queries are lightweight (indexed tables) and assets only load on product and cart pages.