Checkout Upsells Page¶

Menu Location: Products > Checkout Upsells

Overview¶

Checkout Upsells shows a short, limited-time bonus offer to customers right after they finish signing up. On the "Registration Complete" page (while the customer still has an open order), a small carousel of hand-picked products appears with a countdown timer and an optional per-product discount. The goal is to capture a quick add-on purchase while the customer is still in a buying mindset.

This is a single site-wide offer, not a list of configurable campaigns - you turn it on, pick the products, set an optional discount on each, write the headline, and choose how many minutes the countdown runs.

A customer's bonus pick is durable: it's recorded the moment they click Add, even if they don't have an open order yet, and it survives weekly order regeneration. It's automatically placed onto the customer's first order as soon as one exists (on login or the next time their order builds).

Primary Features:

One on/off switch for the whole feature
Configurable offer window (in minutes), timed from the moment the customer's account was created
Custom headline/offer message
Search-and-click product picker - any active, priced product can be featured (stock is only checked when the offer displays to a customer, not when you add it here)
Per-product bonus discount (0-100%)
Products auto-hide if out of stock or has no retail price
A preview link and an admin-only test button to exercise the real discounted-add flow without waiting for a live signup
A durable pick: bonus selections survive order regeneration and land on the customer's first order automatically
A Customer Selections report showing what's being picked and whether it made it onto an order
A Checkout Bonus Selections card on the customer's admin profile (Customer Info page)

Where Customers See It¶

The offer appears on the post-signup "Registration Complete" page (home/first-time.php) when Checkout Upsells is turned on and the customer still has an open (unsubmitted) order. Admins viewing the page always see the offer block (with the test button) even without an open order, so it can be previewed and tested at any time.

Each featured product is shown as a card with:

A "Checkout Bonus!" badge when a discount applies
Product image and name
Struck-through retail price and the discounted price (or just the retail price if no discount is set)
A "Save $X (Y% off)" line when discounted
An Add button

A countdown ("Special Offer Ends In: ...") counts down from the configured number of minutes, starting at the customer's signup time - not at page load. If the customer reloads the page after the window closes, the products disappear and a "This checkout bonus offer has ended" message shows instead (only if products are configured at all).

Clicking Add records the pick immediately and, if the customer already has an open order, applies it to that order right away at the discounted price (or full retail if the window has already closed) - no page reload required. If they don't have an open order yet, the pick is held and applied automatically as soon as one exists.

Configuring Checkout Upsells¶

Settings Panel¶

Go to Products > Checkout Upsells
Check Enable Checkout Upsells to turn the feature on
Set the Offer window (minutes) - how long after signup the countdown/discount runs (default 5, max 1440)
Edit the Headline / offer message shown above the product carousel
Click Save Settings

Choosing Products¶

To add a product:

Type a product name in the Search Products to Add box
Click a result to feature it (already-featured products are excluded from search results)

To set a product's discount:

Enter a percentage (0-100) in the % off box under the product's thumbnail in Featured Upsell Products - it saves automatically
Leave it at 0 to feature the product at full retail price with no badge or "Save" line

To remove a product:

Hover the product card and click Remove

Previewing¶

Use the Preview button (or the Admin: test bonus discount button that appears directly on first-time.php for any admin) to force the offer window open regardless of how long ago the account was created. This lets an admin click through the real Add flow - including the discounted price - on an existing test account. It has no effect for ordinary customers.

How Added Items Behave¶

An item added through the checkout bonus carousel is treated as a locked-in, one-time bonus line on the order:

It is added as its own separate line, even if the customer later adds the same product normally through the shop (the two are never merged/deduped)
Its quantity cannot be changed and it cannot be deleted from the shop cart page
It shows a Checkout Bonus badge wherever it appears in the order (cart, order summary)
Its savings (if discounted) are shown on the cart page alongside the retail price
If the customer's order regenerates for the week (a normal weekly process), the bonus item is automatically re-added so it isn't lost
If the item is removed from the order through another path (e.g. an admin removing it on the order, or the customer moving it back to the cart), the pick is marked removed and will not be added back on the next regeneration
If the featured product goes out of stock or is unfeatured before the customer's order builds, the pick is marked unavailable instead of being added

Customer Selections Report¶

Click View Customer Selections Report at the top of the Checkout Upsells page to see what customers are actually picking.

Shows:

Total distinct customers who have made a pick, and counts of how many picks were added to an order, are still pending (no order to attach to yet), or went unavailable
A per-product breakdown: times selected, added to an order, pending, went unavailable, and the average discount locked in
A From / To date filter (based on when the pick was made), defaulting to the last 30 days
Today, This Week, and Past Month shortcut buttons to quickly change the date range

Use this to see whether the featured products are actually converting into orders, not just being clicked.

Per-product drill-down: click any product name in the report to see the individual customers who picked it - customer name and email, discount locked in, status (added/pending/unavailable/removed), and when they picked it. The drill-down has its own product dropdown and date filter (with the same Today/This Week/Past Month shortcuts) so you can switch products or date ranges without going back to the summary first.

Common Use Cases¶

Feature a couple of bestsellers with a discount¶

Add 2-3 popular, high-margin products, set a modest discount (10-20%) on each, and keep the default 5-minute window - enough urgency without feeling like a bait-and-switch.

Feature products at full price with no discount¶

Add products but leave their discount at 0%. They'll still appear in the carousel (without a badge or "Save" line) as a simple reminder to add them, with no revenue given up.

Give the offer more breathing room¶

Increase the offer window (e.g., to 15-30 minutes) if customers tend to browse the shop for a while right after signing up before returning to check the offer.

Test the discounted-add flow¶

Use the Admin: test bonus discount button on the first-time page (visible only to admins) to force the window open and click through a real Add without needing a fresh signup or waiting out the timer.

Troubleshooting¶

No products showing in the carousel¶

Confirm Enable Checkout Upsells is checked and settings were saved
Confirm at least one product is featured in Featured Upsell Products
A featured product silently drops out of the carousel if it has no retail price or is currently out of stock (in_stock - reserved <= 0) for the current week
Confirm the customer actually has an open order - the block doesn't render at all otherwise

"This checkout bonus offer has ended" showing immediately¶

The offer window (minutes) may be set too low, or the customer's account was created longer ago than the window allows
As an admin, use the Admin: test bonus discount button to force the window open for testing

Add button doesn't work / shows an error¶

"Your session expired, please refresh the page" - the CSRF token expired; refresh and try again
"That item is not available" - the product is no longer featured (or was unfeatured) as an active upsell

A customer's pick never shows up on their order¶

Check the Customer Selections Report (or the Checkout Bonus Selections card on the customer's Customer Info page) for its status - "Pending" means they don't have a qualifying order yet; it applies automatically once one exists
"Unavailable" means the product wasn't offered or was out of stock the week their order built
"Removed" means the item was taken off their order after being added (by the customer or an admin) and won't be re-added automatically

A product search doesn't find what I'm looking for¶

The picker only searches active, non-option, priced products (menu.status = 1, permanent = 1, product_option = 0, retail_price > 0) and excludes products already featured

Products - manage the underlying product catalog and pricing
Store - store categories used elsewhere in the shop
Customer Info - a customer's individual page shows a Checkout Bonus Selections card listing their picks and status, with a link back to this page

Recent Updates¶

2026-07-22¶

Customer Selections Report: added a per-product drill-down (click a product name to see the individual customers who picked it, their status, discount, and pick date)
Customer Selections Report: the date filter now defaults to the last 30 days and adds Today/This Week/Past Month shortcut buttons
Bonus picks are now durable: they're recorded as soon as the customer clicks Add (even without an open order yet) and survive weekly order regeneration instead of being lost
A pick lands automatically on the customer's first order, whether it's already open, built later, or the customer logs back in
Removing a bonus item from an order (by the customer or an admin) now marks the pick removed so it isn't silently re-added on the next regeneration
Added the Customer Selections Report showing pick/add/pending/unavailable counts overall and per product, with a date filter
Added a Checkout Bonus Selections card to the Customer Info page showing that customer's picks and status
Admins now see the offer block on the Registration Complete page even without an open order, for easier previewing
"Sold out" / "no open order" errors on Add are gone since a pick is always recorded regardless of order state

2026-07-21¶

Rebuilt as a dedicated product picker (Products > Checkout Upsells) replacing the old store-category-based configuration
Added a per-product discount percentage, configurable offer-window length, and a customizable headline
Added an admin-only test override button to exercise the real discounted Add flow without waiting for a live signup
Added items now post through a dedicated endpoint and are marked as immutable "Checkout Bonus" lines - locked quantity, cannot be deleted, and never merged with a later normal shop add of the same product
Removed the old farmbox-specific duplicate of the post-signup page