Repository navigation
Feature: Tipping (separate tip_amount, customer-facing selection) #364
Description
Feature: Tipping (separate tip_amount, customer-facing selection)
Summary
Tips must NOT be modeled as discount, tax, or service charge — they have their own ledger value. Add a bill-level tip_amount that is persisted separately for reporting.
Proposed MVP
- Customer picks: No tip / 10% / 15% / 20% / Custom (on the customer-facing display or checkout).
- Store
tip_amounton the bill separately from sale/discount/service charge. - Configurable per store (many merchants want the prompt disabled entirely).
- Foundation only — no staff attribution/pooling/tip-payout reports yet; that would need a proper tip ledger later.
Notes / current state
- There is already a
service_chargeline modeled as a taxed charge (tax packs,main/routes/bills.ts), which is a fee, not a tip. This issue is about a distinct tip value. - Natural home is the customer-facing display work (tip selection on the second screen, cashier confirms, then payment).
Acceptance criteria
-
tip_amountpersisted per bill, reported separately from sale/discount/service charge. - Tip selection UI (percent/custom/none) with store-level enable toggle.
- Cash tips feed shift/day-close reconciliation when Feature: Shift lifecycle management, cash drawer reconciliation, & business day close #279 lands.
Activity
araguz90 commentedon Sep 10, 2026
Hello. First, I want to thank you for the software you’ve created; I’d like to leave a comment and share some ideas regarding this implementation.
I had originally planned to fork the project and implement a tipping function myself, but I see you are already working on something—perhaps an even better implementation than what I had in mind.
Real-world experience:
At our food truck, cash tips are handed over immediately, but card tips involve a more complex workflow. We use a payment terminal that calculates the card surcharge and then asks the customer how much they want to tip (10%, 15%, 20%, custom amount, or no tip). Afterward, we manually note down the tip amount in a notebook (since the payment terminal's software doesn't generate reports showing which staff member received the tip or the specific amount).
First idea:
My idea was simply to implement a way to log servers and tips without affecting the customer's total bill. The server would enter the tip amount into their FloCafe screen; once the payment terminal confirmed the transaction, they would mark the order as paid on the FloCafe screen.
The workflow would look like this:
At checkout:
Select the "Card" payment option.
Display three text fields:
Then, confirm the payment.
Report:
Include a report that allows filtering by date and by server/cashier to show the total tips for the day.
Fraudulent tips
Since Flocafe doesn't have its own dedicated payment gateway (though one might be implemented in the future),
the tip amounts might differ between the two terminals—the Flocafe system and the card payment terminal. However, this can be resolved through regular audits: at the end of the month, the only tip report provided by the payment terminal is the total, and this must match the Flocafe tip report.
That concludes my thoughts on this idea; I hope I’ve conveyed my concept clearly. English isn't my native language. I’m not sure if I’ll be able to implement this in my own Flork instance due to time constraints, but I’d be happy to provide feedback once I see the PR for this feature.
khaira777 commentedon Oct 23, 2026
Update from the #830 support close-out (verified against
main@ 8e39053, 23 Oct):tip_amount,gratuityandtipsreturn 0 hits inmain,sharedandfrontend/src, anddocs/reference/daily-sales-export.mdsays "No tips".service_charge_totalin the daily export.