hospitality.service-charge

export function serviceCharge(lines: readonly BillLine[], basisPoints: number, mode: RoundingMode): ServiceCharge

/** One line of a bill. */
export interface BillLine {
  readonly description: string;
  /** negative for a discount line */
  readonly amount: Money;
  /** false for lines the charge does not apply to */
  readonly eligible: boolean;
}

/** The charge and the totals around it. */
export interface ServiceCharge {
  /** the lines the charge is worked out on */
  readonly eligibleTotal: Money;
  readonly basisPoints: number;
  readonly charge: Money;
  /** every line, before the charge */
  readonly subtotal: Money;
  /** subtotal plus the charge */
  readonly total: Money;
}

import { serviceCharge } from "#fune/hospitality.service-charge@^1";

import { type RoundingMode } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { addMoney } from "./money_add.ts";  ← from money.add ^1.0.0 · built alongside by fune
import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { applyRate } from "./money_apply_rate.ts";  ← from money.apply-rate ^1.0.0 · built alongside by fune
import { sumMoney } from "./money_sum.ts";  ← from money.sum ^1.0.0 · built alongside by fune
import { type BillLine, type ServiceCharge } from "./hospitality_service_charge_types.ts";

/**
 * 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.
 */
export function serviceCharge(lines: readonly BillLine[], basisPoints: number, mode: RoundingMode): ServiceCharge {
  if (lines.length === 0) {
    throw new RangeError("a bill needs at least one line");
  }
  if (!Number.isInteger(basisPoints) || basisPoints < 0 || basisPoints > 10000) {
    throw new RangeError(`basisPoints must be a whole number from 0 to 10000, received ${basisPoints}`);
  }
  const currency = lines[0].amount.currency;
  const subtotal = sumMoney(
    lines.map((line) => line.amount),
    currency,
  );
  const eligibleTotal: Money = sumMoney(
    lines.filter((line) => line.eligible).map((line) => line.amount),
    currency,
  );
  if (eligibleTotal.minor < 0) {
    throw new RangeError(`the eligible lines total ${eligibleTotal.minor}, and a service charge cannot be negative`);
  }
  const charge = applyRate(eligibleTotal, basisPoints, mode);
  return { eligibleTotal, basisPoints, charge, subtotal, total: addMoney(subtotal, charge) };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 5 dependencies, pins them in fune.lock, downloads only the TypeScript 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 TypeScript implementation. Install it without the registry with fune add ./hospitality.service-charge-1.0.0-typescript.fune, or fetch it from a terminal with fune pull hospitality.service-charge@1.0.0:typescript.

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