Split a bill
split_billRead-onlyIdempotent
Use this when the user wants to split a restaurant bill, check, receipt, takeout order, or any single bill between people: evenly or item by item (who had what), with tax, tip, service charge, coupons, delivery fees, or rounding up. Tax, tip, and service charge are shared in proportion to each person's pre-tax subtotal; every share is exact to the cent and the shares add up exactly to the total (largest-remainder rounding). Optional paid_by lists who owes the payer. Does not read receipt photos (pass the items as text), handle several payers or many bills (use settle_group_expenses), or convert currencies.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | Line items from the receipt with who shared each one. Example: [{"description": "Pizza", "price": 24, "shared_by": ["Ana", "Ben"]}, {"description": "Salad", "price": 12, "shared_by": ["Chloe"]}]. Omit and use bill_amount to split one total evenly. | |
| title | No | Optional label, e.g. "Dinner at Luigi's". | |
| people | No | Everyone splitting the bill, e.g. ["Ana", "Ben", "Chloe"]. Needed when some items are shared by everyone or when someone had nothing. Optional if every item lists shared_by. | |
| paid_by | No | Who paid the whole bill, e.g. "Ana". Adds a list of who owes them how much. | |
| currency | No | ISO 4217 code, e.g. USD, EUR, GBP, JPY. Defaults to USD. JPY has no decimals, KWD has three. | |
| tip_base | No | What tip_percent applies to: pre_tax (default, subtotal after discounts) or post_tax (subtotal plus service charge plus tax). | |
| tax_amount | No | Tax in money exactly as printed on the receipt, e.g. 7.38. Shared in proportion to each person's subtotal. | |
| tip_amount | No | Tip in money, e.g. 25. Shared in proportion to each person's subtotal. | |
| bill_amount | No | Use instead of items to split one amount evenly, e.g. 120. It is the amount before any tax_percent or tip_percent you add here; if the bill already includes tax, leave tax out. | |
| round_up_to | No | Round each person's share up to a multiple of this amount, e.g. 1 for whole dollars or 5. The extra is shown separately. | |
| tax_percent | No | Sales tax or VAT rate added on top of the item subtotal (after any discount), e.g. 8.875. Use tax_amount instead when the receipt shows the tax in money. | |
| tip_percent | No | Tip rate, e.g. 18 or 20. Calculated on the pre-tax subtotal unless tip_base is post_tax. | |
| people_count | No | Number of people when names are not given, e.g. 5. They are labelled Person 1 to Person 5. | |
| discount_amount | No | Coupon or deal on the whole bill in money, applied before tax, e.g. 15. | |
| discount_percent | No | Coupon or deal on the whole bill in percent, applied before tax, e.g. 10. | |
| equal_fee_amount | No | A flat fee split equally rather than by what people ordered, e.g. a 6.99 delivery fee or a cover charge. | |
| service_charge_amount | No | Service charge in money, e.g. 9.75. | |
| service_charge_percent | No | Service charge rate added by the restaurant, e.g. 12.5. Shared in proportion to each person's subtotal. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| owes | Yes | ||
| check | Yes | ||
| hints | Yes | ||
| items | Yes | ||
| title | Yes | ||
| labels | Yes | ||
| people | Yes | ||
| totals | Yes | ||
| display | Yes | ||
| paid_by | Yes | ||
| currency | Yes | ||
| settings | Yes | ||
| warnings | Yes | ||
| minor_units | Yes |