SSP — Upsell Popup (Docs)

SSP Documentation

SSP — Upsell Popup

Overview

SSP — Upsell Popup shows a polished modal with product cards that you assign per page. Each card can include unlimited products, optional fixed-price overrides, and skip/hide toggles. You control appearance (headline, colors, sizes) and can add Custom CSS with syntax highlighting. Now includes powerful bundle integration when used with SSP Woo Bundles.

Quick read: The popup can appear once per page load or only once ever (until storage is cleared). Cards are targeted to a specific WordPress page. Bundle popups can automatically appear when customers add individual products that are part of a bundle.

How it Works

You create one or more cards under WooCommerce → Upsell Popup.
Each card is tied to a single WordPress page (ID) and can be triggered by specific products in the cart or all products.
Cards can optionally be triggered only when specific products are in the cart.
Frontend renders a modal shell; products are preloaded server-side and then refreshed via AJAX.
If a product has a fixed-price override, the add-to-cart link carries it and cart totals apply that price.
When SSP Woo Bundles is active, bundle popups can intelligently appear when bundle children are added to cart.

Requires	WooCommerce active.
Storage	LocalStorage keys `ssp_up_ultra_shown_global` (upsells) and `ssp_up_bundle_shown_once` (bundles) when “Show only once” is enabled.
Bundle Integration	Optional. When SSP Woo Bundles is active, additional bundle-specific features are available.

Create Upsell Cards

Go to WooCommerce → Upsell Popup.
Under Upsell Cards tab, click Add New Card (or edit an existing one).
Choose a trigger product (optional) – if set, this card only shows when that specific product is in the cart. Leave as “All Products” to show for any cart.
Add products to upsell. You can add unlimited rows. Optionally set a fixed price for any row.
Choose Skip if product already in cart to avoid showing items the shopper already has.
Toggle Hide price in popup if you want a clean, price-less card.
Select Show this card on page and choose the WordPress page it should appear on.
At the top row you can also set Show popup frequency (per load or only once).
Save changes.

Special “Dynamic” choices

Lowest-priced product
Highest-priced product
Random product

Dynamic choices ignore items already in the cart if “Skip if in cart” is enabled.

Bundle Integration

Requires SSP Woo Bundles: Bundle features are only available when SSP Woo Bundles plugin is installed and active.

How Bundle Popups Work

When a customer adds individual products to their cart that are part of a bundle, the popup can automatically suggest purchasing the bundle instead for better value.

Setup Steps

Install and activate SSP Woo Bundles.
Go to WooCommerce → Upsell Popup → Bundles tab.
Set Popup Priority to choose whether bundles or upsells take precedence when both apply.
Enable individual bundles by checking the Enable checkbox next to each bundle.
Click More Options on any bundle to configure:
- Feature Badges: Add promotional badges with optional green checkmarks.
- Per-item price display: Control how individual item prices are shown (bundle sale/regular or product sale/regular).
- Stats Customization: Configure savings display in Auto or Manual mode.
Under Global Popup Settings, select the page where bundle popups should appear.
Choose popup frequency (per load or only once).

Bundle Stats Modes

Auto Mode	Automatically calculates savings based on product prices and bundle pricing. Supports multiple crossed-out price sources (products bought separately or bundle regular price) and shows configurable savings labels with optional percentage.
Manual Mode	Enter custom prices or completely override with manual text. Useful for special promotions or custom messaging.

Price Display Options

For each bundle, you can control how prices appear on individual items:

Display price source: Bundle (sale/regular) splits the bundle price evenly, or Product (sale/regular) uses the actual product price.
Crossed-out price source: What price appears as the “before” comparison price.

Bundle Behavior

Popup only shows when at least one bundle child product is in the cart.
Bundle itself is not yet in the cart.
When customer clicks “Bundle Now”, individual children are automatically removed from cart and the complete bundle is added.
Live preview in admin shows exactly how stats will appear to customers.

Style & Custom CSS

Upsell Cards Styling

Available under Style Upsell Cards tab:

Headline text + alignment (left/center/right)
Text size (px)
Mobile breakpoint (px) – when layout switches to mobile view
Button label customization
Colors: background, top bar, text, accent border, overlay, button bg/text, close button bg/text

Bundle Styling

Available under Bundle Styling tab (when SSP Woo Bundles is active):

Bundle headline text
Text size and mobile breakpoint
Headline alignment
Bundle “Now” button placement (left/center/right)
Dedicated color scheme for bundle popups (can differ from upsell cards)

Custom CSS: The editor uses WordPress CodeMirror, so you get syntax highlighting. Your CSS is printed after the base styles for reliable overrides. Custom CSS automatically applies to both upsell and bundle popups.

Dynamic Suggestions

Instead of selecting a specific product, choose a special token. The plugin will pick a product at runtime:

Lowest-priced product	Finds the cheapest in-stock product (not in cart if “Skip” is on).
Highest-priced product	Finds the most expensive in-stock product (not in cart if “Skip” is on).
Random product	Picks a random in-stock product (excluding cart items if “Skip” is on).

Dynamic products are cached for 10 minutes (600 seconds) for performance. Cache is automatically cleared when products are updated.

Fixed-Price Overrides

Every suggested product can carry a fixed price. When the shopper clicks Add to cart from the popup:

The link adds ssp_up=1 and a value parameter to the cart URL.
Cart line item stores Upsell price meta (original → adjusted) and sets the runtime price.
If “Hide price in popup” is off, the card shows <del> original and <ins> adjusted.

Example query: ?add-to-cart=123&ssp_up=1&ssp_dt=fixed_price&ssp_dv=19.00

Note: Fixed prices are applied at cart time using WooCommerce hooks, ensuring accurate totals and compatibility with other plugins.

Popup Behavior

General Behavior

Frequency: Show once per page load or Show only once (remembered via localStorage).
Close UX: Click overlay, press Esc, or click the floating × button.
Preload + Refresh: Cards are precomputed server-side and refreshed via AJAX to reflect current cart state.
Mobile Responsive: Automatically adjusts layout at configured breakpoint (default 700px).

Priority System

When both upsell cards and bundle popups could appear on the same page, you can control which takes precedence:

Prioritize Bundles: If a bundle applies, show it instead of upsell cards.
Prioritize Upsells: If an upsell card applies, show it instead of bundle popups.

Trigger Logic

Upsell cards: Show when on the assigned page and (if set) trigger product is in cart.
Bundle popups: Show when on the assigned bundle page and at least one child product is in cart (but bundle itself is not).
Skip conditions prevent showing products already in cart.

FAQ

Popup isn’t showing

Confirm WooCommerce is active.
Make sure your page selection matches the current page.
Check if trigger product (if set) is in the cart.
If set to “Show only once,” clear localStorage or switch to “Per load.”
For bundles, ensure SSP Woo Bundles is active and bundle is enabled.

Prices don’t match

Fixed price must be a non-negative number; it overrides the product’s live price at cart time.
If you hid price in the popup, the cart will still show the adjusted line price.
Bundle prices are calculated based on your display/crossed source settings.

Bundle children aren’t removed from cart

The plugin uses woocommerce_add_to_cart_validation hook to remove children before adding bundle.
Ensure no other plugins are interfering with cart operations.
Check that bundle meta keys _sspprbuf_bundle_items or _bundle_items are properly set.

Stats preview doesn’t match frontend

Preview calculations use the same logic as frontend display.
Ensure bundle has proper regular/sale prices set.
Check that child products have valid prices.
Try switching between Auto and Manual mode to verify settings.

Storage Keys

The plugin uses these localStorage keys:

ssp_up_ultra_shown_global	Tracks if upsell popup has been shown (when frequency = “once”)
ssp_up_bundle_shown_once	Tracks if bundle popup has been shown (when frequency = “once”)
ssp_bundle_open_ids	Admin only – remembers which bundle option sections are expanded

Meta Keys Used

_sspprbuf_bundle_items	Primary bundle children array (SSP Woo Bundles)
_bundle_items	Fallback bundle children array
_sspprbuf_bundle	Cart item meta marking items as part of a bundle
_regular_price	WooCommerce regular price
_sale_price	WooCommerce sale price