# Tip Calculator API
> Work out tips and split a bill — with exact cent maths so the per-person amounts always add back up to the total, no penny ever lost to rounding. The calc endpoint takes a bill, a tip percentage (15% by default) and a number of people and returns the tip amount, the grand total, the per-person amount, the effective tip percentage, and — when you want a tidy number — an optional rounding of the total either up to the next whole unit or to the nearest. When the bill does not divide evenly it produces a fair share list where a few people pay one cent more, so the parts sum precisely. The split endpoint divides any amount, optionally adding a tip first, evenly among people and returns that exact per-person share list. Everything is computed in integer cents locally and deterministically, so it is instant, private and always balances. Currency-agnostic — the numbers work for any currency. Ideal for restaurant and POS apps, expense-sharing and group-payment tools, delivery and service apps, and everyday bill splitting. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This calculates tips and splits; for percentage maths in general use a percentage API and for invoicing margins use a margin API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tip-api/..."
```

## Pricing
- **Free** (Free) — 5,035 calls/Mo, 2 req/s
- **Starter** ($7/Mo) — 14,550 calls/Mo, 8 req/s
- **Pro** ($26/Mo) — 196,500 calls/Mo, 20 req/s
- **Mega** ($64/Mo) — 1,025,000 calls/Mo, 50 req/s

## Endpoints

### Tip

#### `GET /v1/calc` — Calculate tip and total

**Parameters:**
- `bill` (query, required, string) — The bill amount Example: `50`
- `tip_percent` (query, optional, string) — Tip percentage (default 15) Example: `20`
- `people` (query, optional, string) — Split between N people (default 1) Example: `3`
- `round` (query, optional, string) — none (default), up or nearest

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tip-api/v1/calc?bill=50&tip_percent=20&people=3"
```

**Response:**
```json
{
    "data": {
        "tip": 10,
        "bill": 50,
        "total": 60,
        "people": 3,
        "shares": [
            20,
            20,
            20
        ],
        "rounding": "none",
        "per_person": 20,
        "tip_percent": 20,
        "effective_tip_percent": 20
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:18.892Z",
        "request_id": "9db84df4-bb56-4840-b015-d941e5e019b8"
    },
    "status": "ok",
    "message": "Calculate tip and total",
    "success": true
}
```

#### `GET /v1/split` — Split a bill evenly

**Parameters:**
- `amount` (query, required, string) — The amount to split Example: `100`
- `people` (query, optional, string) — Number of people (default 2) Example: `3`
- `tip_percent` (query, optional, string) — Optional tip to add first (default 0)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tip-api/v1/split?amount=100&people=3"
```

**Response:**
```json
{
    "data": {
        "tip": 0,
        "each": 33.33,
        "even": false,
        "total": 100,
        "amount": 100,
        "people": 3,
        "shares": [
            33.34,
            33.33,
            33.33
        ],
        "tip_percent": 0,
        "remainder_cents": 1
    },
    "meta": {
        "timestamp": "2026-06-03T17:42:18.990Z",
        "request_id": "ae8cae34-40cf-41b7-9a06-dafe1621e467"
    },
    "status": "ok",
    "message": "Split a bill evenly",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/tip-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Tip Calculator API",
        "notes": "All maths is done in integer cents to avoid floating-point errors; the shares array always sums exactly to the total, with leftover cents given to the first people. Currency-agnostic — values are plain numbers. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/calc",
                "params": {
                    "bill": "the bill amount (required)",
                    "round": "none (default), up (round total up to a whole unit) or nearest",
                    "people": "split between N people (default 1)",
                    "tip_percent": "tip percentage (default 15)"
                },
                "returns": "the tip, total and per-person amounts"
            },
            {
                "path": "/v1/split",
                "params": {
                    "amount": "the amount to split (required)",
                    "people": "number of people (default 2)",
                    "tip_percent": "optional tip to add first (default 0)"
                },
                "returns": "an exact per-person share list that sums to the total"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "description": "Work out tips and split a bill — with exact cent maths, so the per-person amounts always add back up to the to
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/tip-api
OpenAPI spec: https://www.oanor.com/api/tip-api/openapi.json