> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Recommendations
> Guide upsell, cross-sell, and downsell in the menu — with your rules, Fire spark's engine, or both.
**Recommendations** are the prompts that help customers discover a better fit for their order — a larger combo, an add-on side, or a simpler option when they are about to leave. They sit on top of your synced menu and respect the same channel, store, fulfillment, and schedule rules as everything else you sell.
For marketing and growth teams, recommendations are how you **merchandise in the flow of ordering**, not only on a static category page.
## The three recommendation types
Fire spark supports three types. Each answers a different commercial moment.
| Type | Commercial goal | When to use it | Example |
| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Upsell** | Increase ticket with a **richer or more complete** offer | Customer chose a base item; show the upgraded version or premium customization | Standalone burger → meal combo; standard toppings → premium modifier preset (extra cheese, bacon) |
| **Cross-sell** | Add **complementary items** to the basket | Customer has a main; suggest sides, drinks, or desserts that pair well | Burger → fries or dessert; coffee → pastry |
| **Downsell** | **Protect conversion** with a simpler option | Signals suggest the customer may abandon — price sensitivity, hesitation, or “just the main” intent | Meal combo → burger only; large bundle → single item |
```mermaid theme={null}
flowchart LR
subgraph upsell [Upsell]
A1["Base product"] --> A2["Richer product or premium modifiers"]
end
subgraph cross [Cross-sell]
B1["Main item"] --> B2["Additional product"]
end
subgraph down [Downsell]
C1["Complex offer"] --> C2["Simpler product"]
end
```
### Upsell — sell the more complete version
Use upsell when the customer already wants your category, but you can **expand the order** with a higher-value configuration:
* Upgrade from a single item to a **combo or bundle**
* Surface a **premium modifier preset** (pre-selected quantities on premium toppings)
* Move from a standard size to a larger or featured version
Upsell is not “random extras.” It is the **next step up** in the same purchase intent.
### Cross-sell — sell something extra
Use cross-sell when the main item is right, but the basket can grow with **add-ons that make sense together**:
* Side dishes, drinks, desserts
* Accessories or companion items
* Popular pairings your CRM or analytics already know
Cross-sell adds **parallel lines** to the order; it does not replace what the customer already selected.
### Downsell — save the sale
Use downsell when you would rather **convert at a lower ticket** than lose the customer:
* Offer a single item when the combo feels too much
* Suggest a simpler configuration when behavior shows drop-off risk
* Present a smaller alternative before the customer exits
Downsell is a **recovery lever**, not a discount engine. You still sell real catalog products at real prices.
## Two ways to power recommendations
You can run recommendations in two complementary ways.
### 1. Send recommendations in menu sync (your rules)
During [menu sync](/docs/integrations-api/guides/menu-sync), your integration can include a `recommendations` catalog and link it to products. When you send them, Fire spark **uses exactly what you define** for that product and placement.
This is the right model when:
* You already calculate suggestions in an **external service** (CRM, personalization, data warehouse, aggregator logic)
* You run **A/B tests or campaigns** in your own stack and want Fire spark to reflect them immediately
* You need **full control** over copy, targets, and timing per sync
Your team owns the logic; Fire spark owns **delivery** across channels with operational consistency.
### 2. Fire spark recommendation engine (backoffice)
From the **backoffice**, you can turn on Fire spark's **recommendation engine** per merchant.
When the engine is **on** and you **did not** attach a recommendation to a product in menu sync, Fire spark **generates and surfaces suggestions for you** — upsell, cross-sell, or downsell as appropriate for that context.
When the engine is **off**, or when you **did** send recommendations in sync for that placement, the engine does not override your catalog rules (see precedence below).
This helps especially when:
* The merchant is **new on Fire spark** and you have not built a sync payload for every campaign yet
* Marketing wants to **start fast** while operations keeps syncing the menu from the POS
* You prefer the platform to **merchandise gaps** you have not modeled in your integration
You can enable the engine per merchant and combine it with your own sync rules over time.
## What takes precedence
**Recommendations you send in menu sync always take precedence.** The Fire spark engine only suggests where you left a gap — and only when it is **enabled in the backoffice**.
| Source | When it applies |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Your menu sync** | Always authoritative. If you define a recommendation and link it to a product, Fire spark surfaces **your** version for that placement. |
| **Fire spark engine** | Only when **enabled in backoffice** and you **did not** send a recommendation for that product in sync. |
```mermaid theme={null}
flowchart TD
SYNC["Menu sync payload"]
ENGINE["Fire spark engine (backoffice ON)"]
PLACE["Product placement"]
SYNC -->|"Recommendation linked"| YOURS["Your recommendation"]
SYNC -->|"No recommendation linked"| ENGINE
ENGINE --> OURS["Fire spark suggestion"]
YOURS --> PLACE
OURS --> PLACE
```
In mixed setups:
* Keep **strategic campaigns** in your sync (limited-time upsell, partner promos, CRM-driven cross-sell)
* Leave **unconfigured placements** to the engine when backoffice is on (new products, long-tail cross-sell, stores without a personalization stack)
You never fight your own integration: **your sync wins whenever you send a rule.**
## How Fire spark trains the recommendation engine
Fire spark does not guess in a vacuum. The engine learns from signals you already send and from order behavior on the platform:
| Signal | What we learn from it |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Recommendations in sync** | Your merchandising intent — which products you pair, how you label upsell vs cross-sell vs downsell, and which targets you promote |
| **`bundled_items`** | How combos and bundles are structured — which items belong together operationally |
| **Similar orders** | What customers actually buy together over time, per merchant and context |
| **AI** | Models that combine the signals above to rank and generate suggestions when sync did not define one |
The more you sync — especially explicit recommendations and bundle definitions — the better the engine understands your catalog even before order volume is large. Sync recommendations also **teach** the platform your strategy; they are not only rules the engine must skip when present.
Send strong sync recommendations for hero campaigns, and enable the engine in backoffice to cover everything else. Your sync data improves future engine output even on placements where you later remove manual rules.
## How teams typically work
| Scenario | Suggested approach |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| Mature personalization stack | Send recommendations on every sync; engine off or as backup for uncovered products |
| New merchant on Fire spark | Enable engine in backoffice; sync `bundled_items` and any CRM rules you have — engine learns from both |
| Hybrid | Engine on in backoffice; sync upsells and hero cross-sells; engine fills remaining placements |
| Aggregator-style catalog | Map Uber Eats or POS recommendations in sync; engine respects precedence after normalization |
## What customers experience
Recommendations appear in the ordering flow where your channel UX supports them — as suggested upgrades, add-ons, or simpler alternatives tied to the product they are configuring. They respect:
* **Menu composition** per channel, store, and fulfillment
* **Availability** — out-of-stock targets are not promoted
* **Reachability** — only recommendations whose target product exists in that composed menu are kept
Operations still updates the POS once. Marketing decides **what to suggest**; Fire spark ensures those suggestions stay aligned with what is actually sellable.
## Related resources
How catalogs are composed per channel and context
Modifier groups, pricing, and bundled items
Technical sync flow and recommendation fields
Sample payload for upsell, cross-sell, and downsell