Upsell Groups

Overview

Upsell groups suggest additional products to customers while they order — for example, offering fries and a drink when someone adds a burger. Each group is scoped to one location and pairs a trigger (when the suggestion fires) with a list of suggested items (what gets offered).

Key Purpose: Increase average order value by recommending complementary items at the right moment.

Purpose

This page lets you create and manage upsell groups: rules that decide which products are suggested, when they fire (a specific item, any item from selected categories, or always before checkout), and where they appear (before checkout, and/or alongside the item that triggers them).

Key Concepts

• Upsell Group: A named rule pairing a trigger with a set of suggested ("upsell") items, scoped to one location.
• Title & Subtitle: The customer-facing heading and optional secondary line shown with the suggestion.
• Trigger Type: When the suggestion fires — item (specific products), product_group (any product from selected categories), or checkout (always shown before checkout, regardless of cart contents).
• Trigger Items / Categories: The products (for item) or categories (for product_group) that activate the group. On the Before checkout surface these are matched against what is already in the cart; on With the triggering item they are matched against the item the customer is choosing, before it reaches the cart.
• Display Surfaces: Where the suggestion appears — Before checkout (checkout) and/or With the triggering item (in_flow). At least one is required for item and product_group triggers; a checkout trigger is always forced to Before checkout. The two surfaces render differently on online ordering and on the kiosk — see Customer Impact.
• Suggested Items: The products offered when the group is triggered.
• Status: active or inactive. Inactive groups exist but are paused.
• Per-Location: Each group belongs to one location (location_id).

Route

• Backoffice Route: /marketing/upsell-groups (route name marketing-upsell-groups)
• Create: /marketing/upsell-groups/new
• Edit: /marketing/upsell-groups/edit/:id
• Analytics: /marketing/upsell-groups/analytics (route name marketing-upsell-groups-analytics)
• Navigation: Marketing → Upsell Groups and Marketing → Upsell Analytics (sidebar, under the Marketing group). The analytics page is also reachable from the Analytics button at the top of the Upsell Groups list.
• Per-item: open a product at /menus/items/edit/:id and use the Upsell Groups tab to attach upsell groups to that item and drag to reorder them.

There is no per-location Upsell Groups tab. Manage groups from Marketing → Upsell Groups or from an item's Upsell Groups tab. The reorder endpoint (PUT /back-office/upsell-groups/reorder) exists but is not wired to any screen.

Actions

Create an Upsell Group

Go to Marketing → Upsell Groups and click Create Upsell Group, then fill in the sections:

1. Basic Information — Title (required), optional Subtitle, and Status.
2. How should this upsell be triggered? — choose Item, Product group, or Checkout.
3. Trigger Items (item trigger) or Trigger Categories (product-group trigger) — the section shown depends on the trigger type chosen.
4. Where to show — tick Before checkout and/or With the triggering item (this section is hidden for the checkout trigger, which is forced to Before checkout).
5. Suggested Items — add the products to offer.

Manage Upsells From an Item

When editing a product (Menus → Items → Edit → Upsell Groups tab) you can attach existing upsell groups to that item and drag to reorder them. The links are stored on the item (upsell_group_ids), which is the same source of truth that an item-triggered group's Trigger Items picker syncs.

Activate / Deactivate

Set status to Inactive to pause a group without deleting it; set it back to Active to resume.

---

Fields

Title

• ID: details.title
• Type: Text
• Required: Yes
• Impact: Customer-facing heading shown with the suggestion. Stored under the group's default locale.

Subtitle

• ID: details.subtitle
• Type: Text
• Required: No
• Impact: Optional secondary line shown under the title. Stored under the group's default locale.

Per-language translations of the title/subtitle are handled separately (an "Upsell screen translations" tool), not on this form. The create/edit form itself captures a single title and subtitle.

Status

• ID: status
• Type: Select (active / inactive)
• Required: Yes
• Default: active
• Impact: Marks the group active or paused.

Trigger Type

• ID: trigger_type
• Type: Radio (item / product_group / checkout)
• Required: Yes
• Impact: Decides when the suggestion appears. Switching the type clears the other trigger's selections; switching to checkout also forces display surfaces to checkout and clears trigger items.

Trigger Items

• ID: trigger_items (array of { id })
• Type: Item picker (required when trigger_type = item)
• Impact: Adding any of these items to the cart fires the upsell. The picker can also accept variant groups for Square-integrated merchants (gated by the merchant's Square integration / test mode); the backend expands a variant-group pick to every underlying item at the group's location. Links are stored on each item's upsell_group_ids, not on the group document.

Trigger Categories

• ID: trigger_category_ids (array of category ids)
• Type: Category multi-select (required when trigger_type = product_group)
• Impact: Choosing a product from these categories, or already having one in the cart, fires the upsell. Includes Select all / Clear shortcuts.

Display Surfaces

• ID: display_surfaces (array)
• Type: Checkboxes — checkout, in_flow
• Required: Always required by the API (required|array|min:1), for every trigger type including checkout — posting an empty list returns a 422. For a checkout trigger the form hides this section and submits ['checkout'], and the backend overwrites the value to ['checkout'] regardless of what was sent.
• Labels: checkout = "Before checkout", in_flow = "With the triggering item".
• Impact: Where the suggestion shows. If a group somehow reaches the service layer with no surfaces, it falls back to ['checkout'].

Suggested Items

• ID: items (array of { id }; stored as item_ids)
• Type: Item picker
• Impact: The products suggested to the customer when the group is triggered. The form lets you add as many as you like.

Skip Categories

• ID: skip_category_ids
• Label: Skip categories (NL: Categorieën overslaan), under the section heading Skip when already in the cart (NL: Overslaan als het al in de winkelmand zit)
• Type: Multi-select of categories, optional
• Impact: The group is not shown when the cart already holds an item from one of these categories. The typical use is picking Drinks, so a guest who already added a drink is not asked again. Leave it empty and the group always fires when its trigger matches.

(Verified: upvendo-backend app/Http/Requests/BackOffice/UpsellGroup/StoreUpsellGroupRequest.php:54-55, app/RawModels/UpsellGroup.php:49,99, pushed to the channels at app/RawModels/Location.php:1193; upvendo-backoffice src/components/forms/UpsellGroupForm.vue:427-437, labels src/plugins/i18n/locales/modules/{en,nl}/upsell-groups.ts:52-53,98-99.)

---

Attribution and Analytics

When a customer adds a suggested product from an upsell group, the group's id is stamped onto that order line (upsell_group_id on the order's item snapshot), so the sale can be attributed back to the suggestion that produced it.

• Only regular cart adds carry attribution. Loyalty and free lines never do.
• Attribution is captured on the Online Ordering and Kiosk create-intent paths.

Upsell Analytics page (back office)

Open Marketing → Upsell Analytics, or click Analytics on the Upsell Groups list. The page shows figures for the location selected in the top bar:

• Date filter: From Date / To Date, pre-filled with the current month to date (the first of the month up to today). Clear both to see all time.
• Four summary tiles: Upsell Revenue, Items Added, Orders with Upsell and Attach Rate.
• Performance by group: a sortable table with Upsell Group, Items Added, Orders and Revenue per group.
• If there were no upsell sales in the period, the table reads "No upsell activity in the selected period". If the figures cannot be loaded, it reads "Upsell analytics are not available yet for this location."

The Upsell Groups list itself also shows Added and Revenue columns for each group. Those two columns are all-time totals for the selected location (the list has no date filter) and show "—" when a group has no figures or the figures cannot be loaded.

Both the page and the columns need the same permission as viewing upsell groups (view-upsell-groups). The page title, the tiles, the table, the Analytics button and the Added / Revenue column headers currently exist in English only, so back-office users in other languages see that wording in English.

GET /back-office/upsell-groups/analytics returns the aggregate, gated on view-upsell-groups:

Parameter	Required	Notes
location_id	Yes	Analytics are location-scoped
date_from	No	Inclusive, YYYY-MM-DD
date_to	No	Inclusive, YYYY-MM-DD, not before date_from

Omitting both dates gives an all-time aggregation.

Per group: added_count (how many times a suggestion from this group was added), orders_count (how many distinct orders contained one), revenue, and currency. Groups are returned most-used first.

Summary: total_added, total_orders, total_revenue, currency, and attach_rate — the share of paid orders that contained at least one upsell.

Notes on how the numbers are built:

• Only paid/completed orders are counted. Abandoned and unpaid carts never appear.
• Revenue is the realized line total net of line discounts, normalized to major units in the location's currency — not the list price of the suggested item.
• A group that was later deleted still shows a name: title resolution falls back to soft-deleted groups so historical attribution is not reported against a blank row.

---

Business Rules

• An item-triggered group requires at least one trigger item; a product_group-triggered group requires at least one category.
• The checkout trigger needs no trigger selection, is always forced to Before checkout, and clears any trigger items.
• Every trigger type requires at least one display surface at the API level (Before checkout or With the triggering item); for a checkout trigger the value is then overwritten to Before checkout.
• For item triggers, the link lives on the item (Item.upsell_group_ids) — both the group's Trigger Items picker and the item editor's Upsell Groups tab write to this same source of truth.
• A variant-group pick on an item trigger expands to every item under that variant group at the group's location.
• Upsell groups are scoped per location; create them for each location that should show them.
• Saving, updating, or deleting a group triggers a menu reload for the affected location.

---

Customer Impact

• Where suggestions appear: per the group's display surfaces — before checkout (checkout) and/or alongside the triggering item (in_flow). The two ordering channels render the same surfaces differently.
• Receipts: No direct impact; upsold items appear as normal line items once added.

Where each surface shows, per channel

Online ordering

• Before checkout (checkout): the suggestions are a list underneath the line items in the shopping bag, and they stay visible on the checkout page. They scroll with the order rather than covering it, and appear only once the bag has something in it. There is no separate full-screen upsell page before checkout — proceeding from the bag goes straight to checkout.
• With the triggering item (in_flow): the suggestions are shown inside the item window, under the item's modifier groups, while the customer is still choosing that item — so they are matched against the item being configured, before it is added to the bag. There is no popup after adding to the bag.
• Opening a suggestion that has its own modifiers opens a second item window on top of the first. That second window does not offer upsells of its own, so suggestions never chain.
• Editing an item that is already in the bag does not show suggestions.

Kiosk

• Before checkout (checkout): a full-screen suggestion step shown when the customer opens the order overview, before checkout. If no group is eligible, the order overview opens directly.
• With the triggering item (in_flow): a popup shown after the item is added to the order.

Which suggested items a customer actually sees

Both channels:

• Hidden and Inactive items are removed from the group entirely — including items that were hidden or made unavailable through their reporting category. The customer never sees them in the suggestion list.
• The whole group is skipped when nothing in it is orderable — if every suggested item is Unavailable and/or out of stock, the upsell does not appear at all.
• Online ordering additionally drops an item unless its channel list is empty or includes online ordering; the kiosk applies the same check against the kiosk channel.

Unavailable and out-of-stock suggestions are handled differently per channel:

• Online ordering removes them from the list. Because the suggestions sit inline among the item's own options and the bag's line items, a dead row would only push the real choices further down. A group left with nothing orderable disappears entirely.
• The kiosk keeps them visible but greyed-out, labelled "Unavailable" or "Out of Stock", and they cannot be added. A group still shows as long as one item is orderable; the rest stay greyed-out.

---

FAQs

• "Hoe stel ik upselling in? / How do I set up upselling?" Go to Marketing → Upsell Groups and click Create Upsell Group. Give it a title, choose when it fires (a specific item, a product group, or always at checkout), tick where it shows, and add the items to suggest. Optionally set Skip categories so it stays quiet when the cart already holds, say, a drink.

• "How do I set up upsells?" → Create an upsell group under Marketing → Upsell Groups: give it a title, choose a trigger, pick where to show it, and add the items to suggest.

• "What's the difference between the two display surfaces?" → "Before checkout" (checkout) shows the suggestion on the way to payment — a list under the items in the shopping bag on online ordering, a full-screen step when the order overview opens on the kiosk. "With the triggering item" (in_flow) shows it next to the item that fired it — inside the item window on online ordering, as a popup after adding on the kiosk. You can use either or both (the checkout trigger always uses Before checkout).

• "Why don't I see the old upsell screen before checkout any more?" → On online ordering the separate full-screen upsell page was replaced by suggestions shown where the customer already is: inside the item window while they choose, and under the line items in the shopping bag. The same groups are used; nothing needs reconfiguring. The kiosk still uses a full-screen step.

• "Can I suggest different items per location?" → Yes, each upsell group belongs to one location.

• "How do I suggest something at checkout regardless of the cart?" → Use the checkout trigger type.

• "Where do I manage upsells for one specific product?" → Open the item and use its Upsell Groups tab, or set the group's trigger type to Item and add the product as a trigger item.

• "Can I trigger on a whole category?" → Yes, use the Product group trigger and select one or more categories.

• "Where can I see how my upsells perform?" → Go to Marketing → Upsell Analytics (or click Analytics on the Upsell Groups list). It shows upsell revenue, items added, orders with an upsell and the attach rate for the selected location, plus a per-group table, with a date filter that starts at the current month. The Upsell Groups list also shows all-time Added and Revenue per group. Only paid orders from online ordering and the kiosk are counted.

---

Troubleshooting

• Upsell never fires → For item triggers, ensure the exact item (or a variant group covering it) is selected as a trigger item; for product_group, ensure the selected categories contain the products customers actually add.
• My upsell group stopped appearing → Check that at least one suggested item is Active and in stock. A group whose items are all Unavailable and/or sold out is skipped entirely, and Hidden/Inactive items are dropped from the group before it is evaluated. On online ordering, also check the suggested items are enabled for the online-ordering channel.
• Fewer suggestions show on online ordering than on the kiosk → Expected. Online ordering removes Unavailable and out-of-stock suggestions from the list; the kiosk shows them greyed-out. The group is the same — the difference is what each channel does with items that cannot be ordered right now.
• Suggestion appears in the wrong place → Check the group's display surfaces (Before checkout vs With the triggering item).
• Suggestion shows the wrong items → Review the group's Suggested Items list.
• Trigger items don't stick after switching trigger type → Switching away from the Item trigger clears trigger items (and switching to Checkout clears them too); re-add them after settling on Item.

---

Assistant Guidance

When answering questions about upsells:

• Point users to Marketing → Upsell Groups (click Create Upsell Group), or the Upsell Groups tab on an item. There is no Upsell Groups tab on a location.
• For performance questions ("how much do my upsells bring in?"), point to Marketing → Upsell Analytics. Do not send merchants to the API endpoint.
• Explain the three trigger types (Item, Product group, Checkout) and the two display surfaces (Before checkout = checkout, With the triggering item = in_flow).
• Do not describe the checkout surface as showing after payment — it is shown on the way to checkout, not once the order is paid. Do not describe the in_flow surface as a popup on online ordering; it is a popup only on the kiosk.
• When a merchant asks where a suggestion will show, answer per channel — the same group renders inline on online ordering and full-screen/popup on the kiosk (see Customer Impact).
• The customer-facing text is Title + optional Subtitle; per-language translation is a separate tool, not part of this form.
• Note that groups are per-location, and that item-trigger links are stored on the item itself.

---

Relations

Depends On

• Menu Items / Categories: Triggers and suggestions reference existing items, variant groups, and categories.
• Locations: Each group is scoped to a location; it is managed from Marketing → Upsell Groups, not from the location form.

Affects

• Menu Items: An item trigger writes to each item's upsell_group_ids.
• Kiosk / Online Ordering: Groups are served to the location's ordering channels, which filter the suggested items by status, stock and channel (see Customer Impact).