Zovo Bill Splitter

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.

{
  "type": "object",
  "properties": {
    "items": {
      "description": "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.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "description": "What it was, e.g. \"Margherita pizza\" or \"Bottle of wine\".",
            "type": "string",
            "maxLength": 80
          },
          "price": {
            "type": "number",
            "description": "Price of one unit before tax and tip, in the bill currency, e.g. 18.50."
          },
          "quantity": {
            "description": "How many units, e.g. 2 for two beers at the same price. Defaults to 1.",
            "type": "number"
          },
          "shared_by": {
            "description": "Names of the people who shared this item, e.g. [\"Ana\", \"Ben\"]. Omit (or use [\"everyone\"]) for an item everyone shared. Repeating a name gives that person an extra share.",
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 40
            }
          },
          "weights": {
            "description": "Optional unequal portions in the same order as shared_by, e.g. [2, 1] when Ana ate twice as much as Ben.",
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "number"
            }
          }
        },
        "required": [
          "price"
        ]
      }
    },
    "bill_amount": {
      "description": "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.",
      "type": "number"
    },
    "people": {
      "description": "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.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "people_count": {
      "description": "Number of people when names are not given, e.g. 5. They are labelled Person 1 to Person 5.",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "currency": {
      "description": "ISO 4217 code, e.g. USD, EUR, GBP, JPY. Defaults to USD. JPY has no decimals, KWD has three.",
      "type": "string",
      "maxLength": 8
    },
    "tax_percent": {
      "description": "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.",
      "type": "number"
    },
    "tax_amount": {
      "description": "Tax in money exactly as printed on the receipt, e.g. 7.38. Shared in proportion to each person's subtotal.",
      "type": "number"
    },
    "tip_percent": {
      "description": "Tip rate, e.g. 18 or 20. Calculated on the pre-tax subtotal unless tip_base is post_tax.",
      "type": "number"
    },
    "tip_amount": {
      "description": "Tip in money, e.g. 25. Shared in proportion to each person's subtotal.",
      "type": "number"
    },
    "tip_base": {
      "description": "What tip_percent applies to: pre_tax (default, subtotal after discounts) or post_tax (subtotal plus service charge plus tax).",
      "type": "string",
      "enum": [
        "pre_tax",
        "post_tax"
      ]
    },
    "service_charge_percent": {
      "description": "Service charge rate added by the restaurant, e.g. 12.5. Shared in proportion to each person's subtotal.",
      "type": "number"
    },
    "service_charge_amount": {
      "description": "Service charge in money, e.g. 9.75.",
      "type": "number"
    },
    "discount_percent": {
      "description": "Coupon or deal on the whole bill in percent, applied before tax, e.g. 10.",
      "type": "number"
    },
    "discount_amount": {
      "description": "Coupon or deal on the whole bill in money, applied before tax, e.g. 15.",
      "type": "number"
    },
    "equal_fee_amount": {
      "description": "A flat fee split equally rather than by what people ordered, e.g. a 6.99 delivery fee or a cover charge.",
      "type": "number"
    },
    "round_up_to": {
      "description": "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.",
      "type": "number"
    },
    "paid_by": {
      "description": "Who paid the whole bill, e.g. \"Ana\". Adds a list of who owes them how much.",
      "type": "string",
      "maxLength": 40
    },
    "title": {
      "description": "Optional label, e.g. \"Dinner at Luigi's\".",
      "type": "string",
      "maxLength": 80
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "const": "bill"
    },
    "title": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "minor_units": {
      "type": "number"
    },
    "people": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "items": {
            "type": "string"
          },
          "discount": {
            "type": "string"
          },
          "service_charge": {
            "type": "string"
          },
          "tax": {
            "type": "string"
          },
          "tip": {
            "type": "string"
          },
          "fee": {
            "type": "string"
          },
          "rounding": {
            "type": "string"
          },
          "total": {
            "type": "string"
          },
          "display_total": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "items",
          "discount",
          "service_charge",
          "tax",
          "tip",
          "fee",
          "rounding",
          "total",
          "display_total"
        ],
        "additionalProperties": false
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "price": {
            "type": "string"
          },
          "quantity": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "everyone": {
            "type": "boolean"
          },
          "shared_by": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "weights": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "shares": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "description",
          "price",
          "quantity",
          "amount",
          "everyone",
          "shared_by",
          "weights",
          "shares"
        ],
        "additionalProperties": false
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "subtotal": {
          "type": "string"
        },
        "discount": {
          "type": "string"
        },
        "service_charge": {
          "type": "string"
        },
        "tax": {
          "type": "string"
        },
        "tip": {
          "type": "string"
        },
        "fee": {
          "type": "string"
        },
        "rounding": {
          "type": "string"
        },
        "total": {
          "type": "string"
        }
      },
      "required": [
        "subtotal",
        "discount",
        "service_charge",
        "tax",
        "tip",
        "fee",
        "rounding",
        "total"
      ],
      "additionalProperties": false
    },
    "display": {
      "type": "object",
      "properties": {
        "subtotal": {
          "type": "string"
        },
        "discount": {
          "type": "string"
        },
        "service_charge": {
          "type": "string"
        },
        "tax": {
          "type": "string"
        },
        "tip": {
          "type": "string"
        },
        "fee": {
          "type": "string"
        },
        "rounding": {
          "type": "string"
        },
        "total": {
          "type": "string"
        }
      },
      "required": [
        "subtotal",
        "discount",
        "service_charge",
        "tax",
        "tip",
        "fee",
        "rounding",
        "total"
      ],
      "additionalProperties": false
    },
    "labels": {
      "type": "object",
      "properties": {
        "tax": {
          "type": "string"
        },
        "tip": {
          "type": "string"
        },
        "service_charge": {
          "type": "string"
        },
        "discount": {
          "type": "string"
        }
      },
      "required": [
        "tax",
        "tip",
        "service_charge",
        "discount"
      ],
      "additionalProperties": false
    },
    "settings": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "paid_by": {
      "type": [
        "string",
        "null"
      ]
    },
    "owes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "display": {
            "type": "string"
          }
        },
        "required": [
          "from",
          "to",
          "amount",
          "display"
        ],
        "additionalProperties": false
      }
    },
    "check": {
      "type": "object",
      "properties": {
        "shares_sum": {
          "type": "string"
        },
        "equals_total": {
          "type": "boolean"
        }
      },
      "required": [
        "shares_sum",
        "equals_total"
      ],
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "hints": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "kind",
    "title",
    "currency",
    "minor_units",
    "people",
    "items",
    "totals",
    "display",
    "labels",
    "settings",
    "paid_by",
    "owes",
    "check",
    "warnings",
    "hints"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when a group (trip, vacation, roommates, couple, event) has several shared expenses paid by different people and wants to know who owes who and how to settle up. Each expense can be split equally, by exact amounts, by percentages, or by shares. Returns each person's balance (paid minus share, summing to exactly zero) and the fewest payments that settle every balance to the cent, plus a CSV of payments, balances, and expenses. One currency per call: mixed currencies are rejected and nothing is converted. Does not send payment requests, move money, or remember the group; for one restaurant bill use split_bill.

{
  "type": "object",
  "properties": {
    "expenses": {
      "maxItems": 300,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "description": "What it was for, e.g. \"Airbnb\" or \"Groceries\".",
            "type": "string",
            "maxLength": 80
          },
          "amount": {
            "description": "Total paid, e.g. 360. Optional only for split exact, where it defaults to the sum of the amounts.",
            "type": "number"
          },
          "currency": {
            "description": "ISO 4217 code if different from the top-level currency. All expenses in one call must share one currency.",
            "type": "string",
            "maxLength": 8
          },
          "paid_by": {
            "type": "string",
            "maxLength": 40,
            "description": "The one person who paid, e.g. \"Ana\"."
          },
          "split_among": {
            "description": "Who shares this cost, e.g. [\"Ana\", \"Ben\", \"Chloe\"]. Omit or use [\"everyone\"] for the whole group. The payer is included only if listed.",
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 40
            }
          },
          "split": {
            "description": "How to divide it: equal (default), exact (money amounts per person), percent (must add up to 100), or shares (weights such as 2 nights vs 1 night).",
            "type": "string",
            "enum": [
              "equal",
              "exact",
              "percent",
              "shares"
            ]
          },
          "split_values": {
            "description": "Per-person values for exact, percent, or shares, keyed by name, e.g. {\"Ana\": 2, \"Ben\": 1} for shares or {\"Ana\": 45.5, \"Ben\": 14.5} for exact.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "number"
            }
          }
        },
        "required": [
          "paid_by"
        ]
      },
      "description": "Every shared expense. Example: [{\"description\": \"Airbnb\", \"amount\": 360, \"paid_by\": \"Ana\"}, {\"description\": \"Gas\", \"amount\": 90, \"paid_by\": \"Ben\", \"split_among\": [\"Ben\", \"Chloe\"]}]. Record a repayment already made as an expense paid_by the person who paid it back, with split_among set to the person who received it."
    },
    "people": {
      "description": "Everyone in the group, e.g. [\"Ana\", \"Ben\", \"Chloe\", \"Dev\"]. Needed when \"everyone\" should include someone who never paid. Optional otherwise.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "currency": {
      "description": "ISO 4217 code for every expense, e.g. USD, EUR, GBP. Defaults to USD. Mixed currencies are rejected; nothing is converted.",
      "type": "string",
      "maxLength": 8
    },
    "title": {
      "description": "Optional label, e.g. \"Lisbon trip\".",
      "type": "string",
      "maxLength": 80
    }
  },
  "required": [
    "expenses"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "const": "settle"
    },
    "title": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "minor_units": {
      "type": "number"
    },
    "people": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "paid": {
            "type": "string"
          },
          "share": {
            "type": "string"
          },
          "balance": {
            "type": "string"
          },
          "display_balance": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "gets_back",
              "owes",
              "settled"
            ]
          }
        },
        "required": [
          "name",
          "paid",
          "share",
          "balance",
          "display_balance",
          "status"
        ],
        "additionalProperties": false
      }
    },
    "transfers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "display": {
            "type": "string"
          }
        },
        "required": [
          "from",
          "to",
          "amount",
          "display"
        ],
        "additionalProperties": false
      }
    },
    "transfer_count": {
      "type": "number"
    },
    "nonzero_balances": {
      "type": "number"
    },
    "minimal": {
      "type": "boolean"
    },
    "expenses": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "paid_by": {
            "type": "string"
          },
          "split": {
            "type": "string"
          },
          "split_among": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "split_values": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "description",
          "amount",
          "paid_by",
          "split",
          "split_among",
          "split_values"
        ],
        "additionalProperties": false
      }
    },
    "expenses_shown": {
      "type": "number"
    },
    "expense_count": {
      "type": "number"
    },
    "totals": {
      "type": "object",
      "properties": {
        "spent": {
          "type": "string"
        },
        "moved": {
          "type": "string"
        }
      },
      "required": [
        "spent",
        "moved"
      ],
      "additionalProperties": false
    },
    "display": {
      "type": "object",
      "properties": {
        "spent": {
          "type": "string"
        },
        "moved": {
          "type": "string"
        }
      },
      "required": [
        "spent",
        "moved"
      ],
      "additionalProperties": false
    },
    "downloads": {
      "type": "object",
      "properties": {
        "csv": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "hints": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "kind",
    "title",
    "currency",
    "minor_units",
    "people",
    "transfers",
    "transfer_count",
    "nonzero_balances",
    "minimal",
    "expenses",
    "expenses_shown",
    "expense_count",
    "totals",
    "display",
    "downloads",
    "warnings",
    "hints"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}

Use this when roommates or housemates want to split rent fairly: by bedroom size (square feet or metres) with a shared-space portion split per occupant, by income, or equally, with optional per-room adjustments (private bathroom, no window), couples sharing a room, and utilities split per occupant. Every amount is exact to the cent and the parts add up exactly to the rent. Does not give legal or tenancy advice, collect rent, or handle one-off shared expenses (use settle_group_expenses for those).

{
  "type": "object",
  "properties": {
    "total_rent": {
      "type": "number",
      "description": "Total monthly rent for the home, e.g. 3200."
    },
    "rooms": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 40,
            "description": "Who lives there or the room label, e.g. \"Ana\" or \"Big room (Ana & Ben)\"."
          },
          "size": {
            "description": "Bedroom floor area in any one unit used for all rooms (square feet or square metres), e.g. 140.",
            "type": "number"
          },
          "occupants": {
            "description": "People sharing this room, e.g. 2 for a couple. Shared space and extra costs are split per occupant. Defaults to 1.",
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991
          },
          "adjustment_percent": {
            "description": "Optional premium or reduction on the room's size-based part, e.g. 10 for a private bathroom or -10 for no window.",
            "type": "number"
          },
          "income": {
            "description": "Monthly or yearly income (same period for everyone) when splitting by income, e.g. 5200.",
            "type": "number"
          }
        },
        "required": [
          "name"
        ]
      },
      "description": "Each bedroom or person. Example: [{\"name\": \"Ana\", \"size\": 160}, {\"name\": \"Ben\", \"size\": 120}, {\"name\": \"Chloe\", \"size\": 100}]."
    },
    "basis": {
      "description": "How to split: room_size (default when every room has a size), income (in proportion to income), or equal (per occupant).",
      "type": "string",
      "enum": [
        "room_size",
        "income",
        "equal"
      ]
    },
    "shared_area": {
      "description": "Area of shared space (kitchen, living room, shared bathroom) in the same unit as the room sizes, e.g. 400. Its share of the total area is split equally per occupant.",
      "type": "number"
    },
    "shared_percent": {
      "description": "Alternative to shared_area: percent of the rent treated as shared space and split equally per occupant, e.g. 40. Defaults to 50 for room_size when shared_area is not given.",
      "type": "number"
    },
    "extra_costs": {
      "description": "Other monthly costs split equally per occupant, e.g. 180 for utilities and internet.",
      "type": "number"
    },
    "currency": {
      "description": "ISO 4217 code, e.g. USD, EUR, GBP. Defaults to USD.",
      "type": "string",
      "maxLength": 8
    }
  },
  "required": [
    "total_rent",
    "rooms"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "const": "rent"
    },
    "currency": {
      "type": "string"
    },
    "minor_units": {
      "type": "number"
    },
    "basis": {
      "type": "string"
    },
    "rooms": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "size": {
            "type": [
              "string",
              "null"
            ]
          },
          "occupants": {
            "type": "number"
          },
          "adjustment_percent": {
            "type": [
              "string",
              "null"
            ]
          },
          "income": {
            "type": [
              "string",
              "null"
            ]
          },
          "size_part": {
            "type": "string"
          },
          "shared_part": {
            "type": "string"
          },
          "extras_part": {
            "type": "string"
          },
          "total": {
            "type": "string"
          },
          "display_total": {
            "type": "string"
          },
          "per_person": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "percent_of_rent": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "size",
          "occupants",
          "adjustment_percent",
          "income",
          "size_part",
          "shared_part",
          "extras_part",
          "total",
          "display_total",
          "per_person",
          "percent_of_rent"
        ],
        "additionalProperties": false
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "rent": {
          "type": "string"
        },
        "extra_costs": {
          "type": "string"
        },
        "shared_pool": {
          "type": "string"
        },
        "size_pool": {
          "type": "string"
        },
        "total": {
          "type": "string"
        }
      },
      "required": [
        "rent",
        "extra_costs",
        "shared_pool",
        "size_pool",
        "total"
      ],
      "additionalProperties": false
    },
    "display": {
      "type": "object",
      "properties": {
        "rent": {
          "type": "string"
        },
        "extra_costs": {
          "type": "string"
        },
        "total": {
          "type": "string"
        }
      },
      "required": [
        "rent",
        "extra_costs",
        "total"
      ],
      "additionalProperties": false
    },
    "shared_percent": {
      "type": [
        "string",
        "null"
      ]
    },
    "shared_source": {
      "type": [
        "string",
        "null"
      ]
    },
    "settings": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "assumptions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "warnings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "hints": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "kind",
    "currency",
    "minor_units",
    "basis",
    "rooms",
    "totals",
    "display",
    "shared_percent",
    "shared_source",
    "settings",
    "assumptions",
    "warnings",
    "hints"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "additionalProperties": false
}