Concepts
This page explains how Ultimate Upsell Engine is put together and why. Nothing here is required to use the plugin — but it makes the behaviour predictable.
An offer is content × audience × placement
Every offer answers three independent questions:
- What is shown? A Shopware CMS page (the layout), plus per-offer overrides for products and texts.
- Who sees it? A set of Rule Builder rules. All rules must match; no rules means everyone.
- Where does it appear? Exactly one of seven storefront slots, from the product page to the order confirmation.
The three axes never mix: changing the audience never touches the content, moving an offer to another slot never changes who sees it. That is why the editor has separate When, Where and Content tabs.
Why offers are CMS pages
The plugin has no content editor of its own — an offer's content is a Shopping Experiences layout. This has three practical consequences:
- No new editor to learn. Whoever builds landing pages in your shop can build offers.
- No limits. Any CMS element works inside an offer — the plugin's upsell elements (product slider, product row, CTA, countdown, free-shipping bar) plus every standard element (text, images, video, forms).
- Layouts are shared, offers are specific. Several offers can use the same layout; each offer overrides just its own products and texts ("What this offer shows"). Editing the shared layout changes the frame for all of them; the per-offer overrides stay put.
The promotion boundary
The plugin draws a hard line between presentation and money:
- The plugin renders widgets, targets audiences and tracks attribution. It never changes cart totals, prices or shipping costs itself.
- All discount math is done by Shopware Promotions — the same engine that powers your other promotions.
When you attach a bundle discount to an offer, the plugin creates a managed Shopware promotion behind the scenes and keeps it in sync with the offer on every save. You keep one promotion system to reason about, discounts show up correctly in orders and reports, and the plugin cannot conflict with promotions you built yourself. The same boundary explains the free-shipping bar: the bar visualises a threshold, while the actual free-shipping rule stays in your shipping configuration.
A consequence worth knowing: a managed promotion that has already been used in orders is deactivated, not deleted when its offer is removed — used promotions are financial records in Shopware.
Slots, not page builders
The seven placement slots are fixed, curated injection points chosen for conversion impact — buy box, cart, drawer, checkout sidebar, thank-you page. The plugin renders offers into these slots through Shopware's template extension points, so any theme that builds on the default theme keeps working. Offers in the checkout sidebar deliberately never modify the cart or the payment flow; post-purchase offers appear only after the order is confirmed.
How tracking and attribution work
Two different mechanisms with different privacy profiles:
- Engagement events (impression, click, accept) are recorded from the shopper's browser — only with consent to the Site engagement analytics cookie. They answer "how many people saw and used this offer?".
- Revenue attribution does not observe the shopper at all. Products added through an offer carry the offer's id on the cart line item; when the order is placed, its revenue is credited to the offer. It answers "what did this offer earn?" from first-party order data.
Raw events are aggregated into per-day statistics once a day and purged after 30 days. This is why today's activity appears in the Stats tab tomorrow, and why the statistics carry no personal data.
Vocabulary
| Term | Meaning |
|---|---|
| Offer | One upsell/cross-sell unit: layout + audience + slot + optional discount |
| Slot | One of the seven fixed storefront positions an offer renders in |
| Layout | The CMS page an offer renders; shared, reusable |
| Slot override | Per-offer replacement of a layout element's products/texts |
| Managed promotion | The Shopware promotion the plugin creates and syncs for a bundle discount |
| Accept | A shopper adding the offered product(s) to the cart from the offer |
| Attributed revenue | Order revenue credited to the offer that produced the line item |