Upvendo Knowledge Base

Appearance

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 at checkout), and where they appear (a post-checkout screen and/or a popup shown when the group is triggered).

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 are in the cart), product_group (any product from selected categories is in the cart), or checkout (always shown at checkout, regardless of cart contents).
  • Trigger Items / Categories: The products (for item) or categories (for product_group) that activate the group.
  • Display Surfaces: Where the suggestion appears — Post-checkout screen (checkout) and/or Popup when triggered (in_flow). At least one is required for item and product_group triggers; a checkout trigger is always forced to the post-checkout screen.
  • 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
  • Navigation: Marketing → Upsell Groups (sidebar, under the Marketing group).
  • 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 Post-checkout screen and/or Popup when triggered (this section is hidden for the checkout trigger, which is forced to the post-checkout screen).
  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: Adding any product from these categories 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 = "Post-checkout screen", in_flow = "Popup when triggered".
  • 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.

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.

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

ParameterRequiredNotes
location_idYesAnalytics are location-scoped
date_fromNoInclusive, YYYY-MM-DD
date_toNoInclusive, 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 the post-checkout screen, and clears any trigger items.
  • Every trigger type requires at least one display surface at the API level (Post-checkout screen or Popup when triggered); for a checkout trigger the value is then overwritten to the post-checkout screen.
  • 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 — a post-checkout screen (checkout) and/or a popup shown when the group is triggered (in_flow).
  • Receipts: No direct impact; upsold items appear as normal line items once added.

Which suggested items a customer actually sees ​

Kiosk and Online Ordering apply the same rules, on both display surfaces:

  • 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.
  • Unavailable items stay visible but greyed-out and cannot be added to the order.
  • The whole group is skipped when nothing in it is orderable — if every suggested item is Unavailable and/or out of stock, the upsell step does not appear at all. A group still shows as long as one item is orderable; the rest remain greyed-out.
  • 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.

FAQs ​

  • "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?" → "Post-checkout screen" (checkout) shows the suggestion on a screen after checkout; "Popup when triggered" (in_flow) shows it as a popup when the group fires. You can use either or both (the checkout trigger always uses the post-checkout screen).
  • "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.

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.
  • Suggestion appears in the wrong place → Check the group's display surfaces (Post-checkout screen vs Popup when triggered).
  • 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.
  • Explain the three trigger types (Item, Product group, Checkout) and the two display surfaces (Post-checkout screen = checkout, Popup when triggered = in_flow).
  • 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).