# Tax Bracket API
> Progressive (marginal) tax-bracket maths as an API. You supply the bracket schedule, so it works for any country, year or tax table and never goes stale, and it is entirely currency-agnostic. The tax endpoint takes an income and a schedule of threshold:rate pairs (with an optional standard deduction) and returns the total tax, the after-tax income, the effective and marginal rates, and a per-bracket breakdown showing exactly how much is taxed in each tier. The reverse endpoint solves the inverse problem — the gross income needed to take home a target net amount on the same schedule — by bisection. The brackets endpoint validates and normalizes a schedule into labelled tiers (adding a 0% tier from zero and marking the open-ended top bracket). Everything is computed locally and deterministically, so it is instant and private. It models only the schedule you provide — fold any allowances, credits or surtaxes into the brackets or the deduction yourself — and it is not tax advice. Ideal for payroll and HR tools, salary and offer calculators, fintech and budgeting apps, and any product that shows take-home pay. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is progressive-tax maths on a schedule you supply; for gross-pay period conversion use a payroll API and for loans and interest use a finance-calculator 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/taxbracket-api/..."
```

## Pricing
- **Free** (Free) — 10,035 calls/Mo, 2 req/s
- **Starter** ($12/Mo) — 19,650 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 246,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,275,000 calls/Mo, 50 req/s

## Endpoints

### Tax

#### `GET /v1/brackets` — Validate / normalize a schedule

**Parameters:**
- `brackets` (query, required, string) — threshold:rate% pairs Example: `0:10,11000:12,44725:22,95375:24,182100:32,231250:35,578125:37`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/taxbracket-api/v1/brackets?brackets=0%3A10%2C11000%3A12%2C44725%3A22%2C95375%3A24%2C182100%3A32%2C231250%3A35%2C578125%3A37"
```

**Response:**
```json
{
    "data": {
        "note": "Normalized, sorted bracket schedule. 'to: null' is the top (open-ended) bracket. A 0% tier from 0 is added if missing.",
        "count": 7,
        "input": {
            "brackets": [
                {
                    "from": 0,
                    "rate": 10
                },
                {
                    "from": 11000,
                    "rate": 12
                },
                {
                    "from": 44725,
                    "rate": 22
                },
                {
                    "from": 95375,
                    "rate": 24
                },
                {
                    "from": 182100,
                    "rate": 32
                },
                {
                    "from": 231250,
                    "rate": 35
                },
                {
                    "from": 578125,
                    "rate": 37
                }
            ]
        },
        "tiers": [
            {
                "to": 11000,
                "from": 0,
                "tier": 1,
                "rate_percent": 10
            },
            {
                "to": 44725,
                "from": 11000,
                "tier": 2,
                "rate_percent": 12
            },
            {
                "to": 95375,
                "from": 44725,
                "tier": 3,
                "rate_percent": 22
            },
            {
                "to": 182100,
                "from": 9
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/reverse` — Gross income for a target net

**Parameters:**
- `net` (query, required, string) — Target take-home Example: `43692.5`
- `brackets` (query, required, string) — threshold:rate% pairs Example: `0:10,11000:12,44725:22,95375:24,182100:32,231250:35,578125:37`
- `deduction` (query, optional, string) — Standard deduction Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/taxbracket-api/v1/reverse?net=43692.5&brackets=0%3A10%2C11000%3A12%2C44725%3A22%2C95375%3A24%2C182100%3A32%2C231250%3A35%2C578125%3A37&deduction=0"
```

**Response:**
```json
{
    "data": {
        "tax": 6307.5,
        "note": "Gross income required to take home the target net, found by bisection on the provided schedule.",
        "input": {
            "brackets": [
                {
                    "from": 0,
                    "rate": 10
                },
                {
                    "from": 11000,
                    "rate": 12
                },
                {
                    "from": 44725,
                    "rate": 22
                },
                {
                    "from": 95375,
                    "rate": 24
                },
                {
                    "from": 182100,
                    "rate": 32
                },
                {
                    "from": 231250,
                    "rate": 35
                },
                {
                    "from": 578125,
                    "rate": 37
                }
            ],
            "deduction": 0,
            "target_net": 43692.5
        },
        "required_gross": 50000,
        "after_tax_income": 43692.5,
        "marginal_rate_percent": 22,
        "effective_rate_percent": 12.615
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:56.567Z",
        "request_id": "2cb06020-621b-4525-9f8a-e9e880a129e0"
    },
    "status": "ok",
    "message": "Gross from net",
    "success": true
}
```

#### `GET /v1/tax` — Progressive tax on a schedule

**Parameters:**
- `income` (query, required, string) — Gross income Example: `50000`
- `brackets` (query, required, string) — threshold:rate% pairs Example: `0:10,11000:12,44725:22,95375:24,182100:32,231250:35,578125:37`
- `deduction` (query, optional, string) — Standard deduction Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/taxbracket-api/v1/tax?income=50000&brackets=0%3A10%2C11000%3A12%2C44725%3A22%2C95375%3A24%2C182100%3A32%2C231250%3A35%2C578125%3A37&deduction=0"
```

**Response:**
```json
{
    "data": {
        "tax": 6307.5,
        "note": "Marginal/progressive tax on the bracket schedule provided. Effective rate is tax ÷ gross income.",
        "input": {
            "income": 50000,
            "brackets": [
                {
                    "from": 0,
                    "rate": 10
                },
                {
                    "from": 11000,
                    "rate": 12
                },
                {
                    "from": 44725,
                    "rate": 22
                },
                {
                    "from": 95375,
                    "rate": 24
                },
                {
                    "from": 182100,
                    "rate": 32
                },
                {
                    "from": 231250,
                    "rate": 35
                },
                {
                    "from": 578125,
                    "rate": 37
                }
            ],
            "deduction": 0,
            "taxable_income": 50000
        },
        "breakdown": [
            {
                "to": 11000,
                "from": 0,
                "rate_percent": 10,
                "tax_in_bracket": 1100,
                "taxable_in_bracket": 11000
            },
            {
                "to": 44725,
                "from": 11000,
                "rate_percent": 12,
                "tax_in_bracket": 4047,
                "taxable_in_bracket": 33725
            },
            {
          
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "You supply the schedule — works for any country/year. Currency-agnostic. Not tax advice.",
        "service": "taxbracket",
        "endpoints": {
            "/v1/tax": "Total tax, effective & marginal rate, after-tax income and per-bracket breakdown for an income.",
            "/v1/reverse": "The gross income needed to take home a target net, on the provided brackets.",
            "/v1/brackets": "Validate and normalize a bracket schedule into labelled tiers."
        },
        "description": "Progressive tax-bracket maths for any schedule you provide: total tax, effective and marginal rates, breakdown, and reverse (gross from net).",
        "bracket_format": "Comma list of threshold:rate% pairs, e.g. \"0:10,11000:12,44725:22,95375:24\". A standard deduction can be passed separately."
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:56.781Z",
        "request_id": "72e2d083-da90-4027-9c9e-97f7356d442c"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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