hospitality.service-charge

def service_charge(lines: Sequence[BillLine], basis_points: int, mode: RoundingMode) -> ServiceCharge

@dataclass(frozen=True)
class BillLine:
    """One line of a bill."""

    description: str
    #: negative for a discount line
    amount: Money
    #: false for lines the charge does not apply to
    eligible: bool

@dataclass(frozen=True)
class ServiceCharge:
    """The charge and the totals around it."""

    #: the lines the charge is worked out on
    eligible_total: Money
    basis_points: int
    charge: Money
    #: every line, before the charge
    subtotal: Money
    #: subtotal plus the charge
    total: Money

from fune.hospitality.service_charge import service_charge  # hospitality.service-charge@^1

from typing import Sequence

from .hospitality_service_charge_types import BillLine, ServiceCharge
from .math_round_div import RoundingMode  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_add import add_money  ← from money.add ^1.0.0 · built alongside by fune
from .money_apply_rate import apply_rate  ← from money.apply-rate ^1.0.0 · built alongside by fune
from .money_sum import sum_money  ← from money.sum ^1.0.0 · built alongside by fune


def service_charge(lines: Sequence[BillLine], basis_points: int, mode: RoundingMode) -> ServiceCharge:
    """A discretionary service charge on the eligible lines of a bill.

    The rate is applied once, to the eligible total, and rounded once. Charging
    each line and adding the pennies up drifts: three 3.33 lines at 12.5% are
    0.42 each, 1.26 in all, where 12.5% of 9.99 is 1.25.
    """
    if len(lines) == 0:
        raise ValueError("a bill needs at least one line")
    if isinstance(basis_points, bool) or not isinstance(basis_points, int) or basis_points < 0 or basis_points > 10000:
        raise ValueError("basisPoints must be a whole number from 0 to 10000, received %s" % (basis_points,))
    currency = lines[0].amount.currency
    subtotal = sum_money([line.amount for line in lines], currency)
    eligible_total = sum_money([line.amount for line in lines if line.eligible], currency)
    if eligible_total.minor < 0:
        raise ValueError(
            "the eligible lines total %d, and a service charge cannot be negative" % (eligible_total.minor,)
        )
    charge = apply_rate(eligible_total, basis_points, mode)
    return ServiceCharge(
        eligible_total=eligible_total,
        basis_points=basis_points,
        charge=charge,
        subtotal=subtotal,
        total=add_money(subtotal, charge),
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 5 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add hospitality.service-charge

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./hospitality.service-charge-1.0.0-python.fune, or fetch it from a terminal with fune pull hospitality.service-charge@1.0.0:python.

The whole function, every language, is one file too: hospitality.service-charge-1.0.0.fune, 18,941 bytes, sha256 2a0ae152d790183164c02f7b44a848c2d7815696806025aca498132d1d764c3c. It installs into a project of any language.

# fune: before hospitality.service-charge

# fune: after hospitality.service-charge

# fune: replace math.round-div in hospitality.service-charge
# fune: replace money.add in hospitality.service-charge
# fune: replace money.amount in hospitality.service-charge
# fune: replace money.apply-rate in hospitality.service-charge
# fune: replace money.sum in hospitality.service-charge

# fune: step hospitality.service-charge after <n|label>

More from the author

- **One rounding step.** The rate is applied once, to the eligible total, and rounded once, in the mode the caller chooses. Charging each line and adding the pennies drifts: three 3.33 lines at 12.5% are 0.42 each (1.26), but 12.5% of 9.99 is 1.25. - **Lines say whether they are eligible.** Venues leave out different things (bar drinks, a corkage fee, a cake brought in), so the function does not guess. A discount line (negative amount) that is eligible lowers the base. - **The rate is a basis-point integer**: 1250 is 12.5%, anything from 0 to 10000.

## Edge cases

- No eligible lines, or a 0 rate, means a charge of 0. - An eligible total below zero (a refund bill) is an error, not a negative charge. - Every line must be in the same currency.

## Not covered

- **VAT.** HMRC treats a genuinely optional service charge as outside the scope of VAT, and a compulsory one as part of the price of the meal, taxed at the meal's rate (VAT Notice 709/1, *Catering and takeaway food*, section on tips and service charges: https://www.gov.uk/guidance/catering-and-take-away-food-vat-notice-7091). This function works out the amount only. Whether the charge is really optional is a fact about how the venue sells, not something it can see. - **Who gets the money.** Under the Employment (Allocation of Tips) Act 2023, service charges an employer controls must be passed to workers in full and shared fairly; see `hospitality.tronc-allocation`.

Files