io.github.grulex/money4k-split-bill

Use this when the user wants to create and share an itemized bill for a restaurant meal or shared purchase, with a link where participants select their own items and calculate their shares. Accept items from a receipt photo, typed list or plain-language description; no receipt or separately supplied grand total is required. For a EUR 20 pizza and two beers at EUR 5 each, submit pizza 1 x 20 and beer 2 x 5, bill total EUR 30. If no total was supplied, calculate it exactly from the stated items; clarify missing currency or ambiguous amounts, and do not invent taxes or fees. Do not call merely to read a receipt, answer simple arithmetic, collect payments or book a restaurant. Use update_bill for changes to an existing bill. Anyone with the returned share_url can view it. Supply positive quantities, nonnegative prices and one currency; each item total_price must equal unit_price times quantity, and bill total_price must equal the sum of item totals. Include separate receipt taxes in the prices of eligible items under local rules, including different food and alcohol tax groups; never create standalone tax items or add included taxes twice. When a receipt or user-supplied final total is present, keep that control total fixed. If totals differ, recheck the source items and correct extraction or arithmetic; never change the control total or invent adjustments to pass validation. After reconciling the receipt, an explicitly requested extra tip adds its exact amount to the bill total; record the receipt total and addition in info, and never add an already included tip twice. Represent requested tips as one selectable item with quantity equal to the explicitly supplied participant count and unit_price equal to total tips divided by that count; ask for a missing count and never round away a remainder. Shared items may be split into selectable portions by dividing their unchanged line total by the requested count. Reconcile discounts and tips before calling; do not guess unclear receipt values. Returns the saved bill, share_url and bill UI. Requires OAuth; no profile lookup is needed. Creation is not idempotent: do not blindly retry after a timeout or an ambiguous server error.

Returns the authenticated user's id, full_name, email and created_at for the bill UI to identify their own item selections. Requires OAuth and uses the user identity from the bearer token. This read-only helper is intended for calls from the app UI.

Use this when the connected user asks to select, change or clear their own items on an existing shared bill, such as one pizza portion and one tip share, for calculating their personal share. Saves absolute item selection quantities for that user; it does not change bill items, prices or the total. Do not use to create or edit a bill, select for friends, or mark a payment as completed. Use actual bill_id and item IDs; quantity 0 clears a selection, and omitted selections remain unchanged. Selections and the user's display name are visible to anyone with the bill link. Cannot select on behalf of other people or collect payments. Requires OAuth; no profile lookup is needed.

Use this when the user asks to edit an existing shared bill: correct an item, rename it, add or remove purchases, add tips by participant count, or divide a shared dish into selectable portions. Replaces the complete content of a public bill owned by the connected user, whether created from a receipt or from words in chat. Do not use for a new bill, a hypothetical question or recording which items a participant chose; use create_bill or set_bill_selections_batch for those respective actions. Supply the existing bill_id and every item to keep, preserving existing item IDs; omitted items and their selections are deleted. New items use an empty ID. Do not send a partial list to correct one item. Each item total_price must equal unit_price times quantity and bill total_price must equal the sum of item totals in one currency. Include taxes in eligible item prices under local rules, never as standalone items. Keep the printed receipt total or an explicitly corrected user-supplied total fixed; resolve mismatches by rechecking extraction and arithmetic, never by balancing adjustments. Support requested edits in chat, including tips and shared portions. For total tips of EUR 50 for 5 people, add one selectable item with quantity 5 and unit_price EUR 10; ask if participant count is missing. Explicitly requested additions or removals change the total only by their exact amount; do not add included tips twice. To split a shared item, set quantity to the requested portion count and divide its existing tax-inclusive line total by that count, preserving line and bill totals. If division is not exact in currency minor units, clarify the allocation before writing. Retained item IDs preserve selected quantities without rescaling; clarify the effect before changing the meaning of units on an already selected item. Returns the updated bill and the same share_url. Requires OAuth; no profile lookup is needed.