Tips Collection

Overview

Tips collection allows customers to add a tip to their order. Configure tip options for Online Ordering, Kiosk, and Table QR.

Key Purpose: Enable and configure tip collection.

Purpose

This feature lets customers add a voluntary gratuity during checkout on Online Ordering, Kiosk, and QR Ordering channels, with configurable percentage options and custom amount entry.

Key Concepts

Per-Channel Configuration: Tip settings are configured independently per channel — In-House Settings (Kiosk/QR) and Online Settings (Online Ordering) — each with their own enabled flag, percentage options, and calculation base
Calculate Tips Setting: The calculate_tips enum (after_taxes or before_taxes) determines whether tip percentages are applied to the total including tax or the subtotal before tax
Mutually Exclusive Input: Both a tip percentage and a custom tip amount are supported, but they are mutually exclusive — the backend rejects requests containing both tip_percentage and tip_amount
Transaction Storage: Tips are stored as tip_amount (float) and tip_percentage (float, rounded to 2 decimals) on the Transaction model and displayed as a separate line on receipts
Kassanet POS Override: For locations using Kassanet POS integration (Hendrickx/Vanhoutte), tip availability is controlled by the POS system's tipCalculatorActivated flag instead of Upvendo settings

Actions

Enable Tip Collection

Toggle collect_tips.enabled for the desired channel in In-House Settings (kiosk/QR) or Online Settings (online ordering).

Configure Percentage Options

Set three percentage values (default: 10%, 15%, 20%). Each value must be between 0 and 100. The options array is required when tips are enabled.

Set Calculation Base

Choose after_taxes (default) or before_taxes to determine the base amount for percentage calculations.

Customer: Select Tip

Choose a percentage option (shows calculated amount), enter a custom amount via numeric keypad (kiosk) or inline input (online ordering), or select "No Tip" to skip.

Location

Backoffice Route: /in-house/settings (In-House)
Backoffice Route: /online-settings (Online)
Backend Controller: Various settings controllers

Fields

Tips Enabled

Property	Value
Field ID	`collect_tips.enabled`
Label	Collect Tips
Type	Toggle
Default	false

Description: Enable tip collection at checkout.

Tip Options

Property	Value
Field ID	`collect_tips.options`
Label	Tip Percentages
Type	Array of Numbers
Default	[10, 15, 20]

Description: Percentage options shown to customers.

Examples:

[10, 15, 20] - Standard
[15, 18, 20, 25] - Higher options
[5, 10, 15] - Lower options

Calculate Tips

Property	Value
Field ID	`collect_tips.calculate_tips`
Label	Calculate Tips
Type	Select
Options	before_taxes, after_taxes
Default	after_taxes

Description: Calculate tip percentage before or after taxes.

Options:

Before Taxes: Tip on subtotal only
After Taxes: Tip on total including tax

Custom Tip Amount

Property	Value
Field ID	`allow_custom_tip`
Label	Allow Custom Amount
Type	Toggle
Default	true

Description: Allow customers to enter custom tip amount.

Per-Channel Settings

In-House (Kiosk)

json

{
  "in_house_setting": {
    "collect_tips": {
      "enabled": true,
      "options": [10, 15, 20],
      "calculate_tips": "after_taxes"
    }
  }
}

Online Ordering

json

{
  "online_settings": {
    "collect_tips": {
      "enabled": true,
      "options": [10, 15, 20],
      "calculate_tips": "after_taxes"
    }
  }
}

Business Logic

Tip Calculation

Subtotal: €25.00
Tax (21%): €5.25
Total: €30.25

Calculate tips: after_taxes
Tip base: €30.25

Tip options:
- 10%: €3.03
- 15%: €4.54
- 20%: €6.05

Customer selects 15%:
Final total: €30.25 + €4.54 = €34.79

Tip Flow

Customer at checkout
    │
    ▼
Tips enabled?
├── No → Skip tip screen
│
└── Yes → Show tip options
          ├── Percentage buttons
          ├── Custom amount input
          └── No tip option
    │
    ▼
Customer selects tip
    │
    ▼
Add to order total
    │
    ▼
Process payment

Business Rules

Tips are only calculated if collect_tips.enabled is true for the applicable channel — disabled means the tip screen is skipped entirely
Only one of tip_percentage or tip_amount can be provided per order; sending both causes a validation error (InvalidArgumentException)
Tip percentage is calculated on subtotal - discount (effective pre-tip base), not on the raw subtotal
Default options are [10, 15, 20] with after_taxes calculation; each percentage must be between 0-100 and the options array is required when tips are enabled
On the kiosk, if the order total is zero or negative (fully discounted), percentage buttons are hidden and only the custom amount option is shown

FAQs

"Where do I configure tip settings?" In-House tips (Kiosk/QR) are at In-House Settings → Checkout. Online ordering tips are at Online Settings → Checkout. Each channel is configured independently.
"What is the difference between 'Before Taxes' and 'After Taxes'?" Before Taxes calculates the tip percentage on the subtotal excluding tax. After Taxes includes tax in the calculation base. Default is After Taxes.
"Can a customer enter any tip amount?" Yes, there is always a "Custom" option alongside the percentage buttons. The customer can enter any numeric amount. A "No Tip" / skip option is also available.
"Do tips work with Kassanet POS integrations?" Yes, but instead of Upvendo's collect_tips setting, the system checks the Kassanet API's tipCalculatorActivated flag. If the POS has tips disabled, no tip screen is shown regardless of Upvendo settings.
"How are tips shown on the receipt?" The tip amount is displayed as a separate line item between taxes/discounts and the final total, on both digital order summaries and printed receipts.

Troubleshooting

Tip screen not showing on kiosk → Verify collect_tips.enabled is true in In-House Settings. For Kassanet POS locations, check that the POS tipCalculatorActivated flag is enabled.
Tip calculation seems wrong → Check whether calculate_tips is set to "Before Taxes" or "After Taxes." The base amount also excludes discounts (calculated on subtotal minus discount).
Custom tip not working → Ensure the customer enters a valid numeric amount. On kiosk, the amount is entered via numeric keypad. On online ordering, it's an inline text input.
Tips not appearing on receipts → Tips are included as a separate line item on receipts. Verify the transaction was completed successfully and the receipt template includes tip display.

Customer Impact

Online Ordering

Tip screen before payment
Percentage buttons
Custom amount option
"No tip" option
Tip shown in order summary

Kiosk

Tip screen on terminal
Large touch-friendly buttons
Quick selection
Skip option

Receipts

Tip amount shown separately
Included in total

Relations

Depends On

Locations: Tips per location
Tax Rates: For calculation base

Affects

Transactions: Tip recorded
Reports: Tip reports
Payments: Total amount

Examples

Standard Tip Setup

json

{
  "collect_tips": {
    "enabled": true,
    "options": [10, 15, 20],
    "calculate_tips": "after_taxes"
  }
}

Higher Tip Options

json

{
  "collect_tips": {
    "enabled": true,
    "options": [15, 18, 20, 25],
    "calculate_tips": "after_taxes"
  }
}

Tips Disabled

json

{
  "collect_tips": {
    "enabled": false,
    "options": [10, 15, 20],
    "calculate_tips": "after_taxes"
  }
}

Tip Selection UI (Kiosk)

╔═══════════════════════════════════════╗
║                                       ║
║         Would you like to             ║
║           add a tip?                  ║
║                                       ║
║   ┌─────────┐ ┌─────────┐ ┌─────────┐║
║   │   10%   │ │   15%   │ │   20%   │║
║   │  €3.03  │ │  €4.54  │ │  €6.05  │║
║   └─────────┘ └─────────┘ └─────────┘║
║                                       ║
║   ┌─────────────────────────────────┐║
║   │      Custom Amount              │║
║   └─────────────────────────────────┘║
║                                       ║
║   ┌─────────────────────────────────┐║
║   │         No Tip                  │║
║   └─────────────────────────────────┘║
║                                       ║
╚═══════════════════════════════════════╝

Order Summary with Tip

Order Summary
─────────────────────────────────────
Margherita Pizza              €12.50
Garlic Bread                   €4.50
2x Cola                        €5.00
─────────────────────────────────────
Subtotal                      €22.00
Tax (21%)                      €4.62
─────────────────────────────────────
Total before tip              €26.62
Tip (15%)                      €3.99
─────────────────────────────────────
TOTAL                         €30.61

Tips Collection ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Enable Tip Collection ​

Configure Percentage Options ​

Set Calculation Base ​

Customer: Select Tip ​

Location ​

Fields ​

Tips Enabled ​

Tip Options ​

Calculate Tips ​

Custom Tip Amount ​

Per-Channel Settings ​

In-House (Kiosk) ​

Online Ordering ​

Business Logic ​

Tip Calculation ​

Tip Flow ​

Business Rules ​

FAQs ​

Troubleshooting ​

Customer Impact ​

Online Ordering ​

Kiosk ​

Receipts ​

Relations ​

Depends On ​

Affects ​

Related Features ​

Examples ​

Standard Tip Setup ​

Higher Tip Options ​

Tips Disabled ​

Tip Selection UI (Kiosk) ​

Order Summary with Tip ​

Tips Collection

Overview

Purpose

Key Concepts

Actions

Enable Tip Collection

Configure Percentage Options

Set Calculation Base

Customer: Select Tip

Location

Fields

Tips Enabled

Tip Options

Calculate Tips

Custom Tip Amount

Per-Channel Settings

In-House (Kiosk)

Online Ordering

Business Logic

Tip Calculation

Tip Flow

Business Rules

FAQs

Troubleshooting

Customer Impact

Online Ordering

Kiosk

Receipts

Relations

Depends On

Affects

Related Features

Examples

Standard Tip Setup

Higher Tip Options

Tips Disabled

Tip Selection UI (Kiosk)

Order Summary with Tip