---
title: "Tax on a bonus or commission payment"
method: POST
path: "/v1/bonus-tax"
tags: ["Calculators"]
---

# Tax on a bonus or commission payment

`POST /v1/bonus-tax`

## Request

- Base URL: `https://api.calculate.co.nz`
- URL: `https://api.calculate.co.nz/v1/bonus-tax`
- Auth: API key in header `X-API-Key`

Work out what is left of a New Zealand bonus after tax.

A bonus is an extra emolument. It is NOT taxed at a flat rate, and not at
your ordinary rate either. The tax on it is the difference between the tax
on your salary plus the bonus and the tax on your salary alone.

That is why a bonus can feel over-taxed and still be right. If it straddles
a bracket, part is taxed at the lower rate and part at the higher one, so
the effective rate on the bonus lands between them and above your salary's
rate. `crosses_bracket` says when this has happened.

`annual_salary` matters: the same bonus costs different amounts of tax
depending on the salary underneath it.

Two edges are handled. ACC stops at the earnings cap, so a salary already
above it means no levy on the bonus at all. Student loan takes 12% of the
whole bonus when the salary is over the repayment threshold, but only of the
part above the threshold when it is not.

An employer may deduct at a flat rate through the year and let IRD square it
up, so a payslip can differ from this while both are correct.

## Request body

- BonusTaxRequest
  - `bonus_amount` number, required: Gross bonus or commission, in NZD.
  - `annual_salary` number, required: Regular annual salary, EXCLUDING the bonus. This decides which tax brackets the bonus falls into, so the answer depends on it.
  - `kiwisaver_rate` number: Employee contribution as a DECIMAL: 0.03 for 3%.
  - `has_student_loan` boolean: Whether repayments are deducted.

## Response `200`

Income tax on the bonus, every other deduction, and what is left.

- BonusTaxResponse
  - `result` BonusTaxResult, required
    - `bonus_amount` number, required: Gross bonus.
    - `annual_salary` number, required: Salary the bonus sits on top of.
    - `tax_on_salary_alone` number, required: Annual income tax on the salary by itself.
    - `tax_on_salary_plus_bonus` number, required: Annual income tax on both together.
    - `income_tax_on_bonus` number, required: The difference between those two, which is what the bonus actually costs in tax. IRD calls this the extra emolument method.
    - `effective_tax_rate_on_bonus` number, required: Tax on the bonus as a percentage of it. Higher than the rate on the salary whenever the bonus crosses a bracket, which is normal and not an error.
    - `acc_levy` number, required: ACC earner levy on the bonus. Zero when the salary alone already exceeds the liable earnings cap, and charged only on the part below the cap when the bonus crosses it.
    - `kiwisaver` number, required: Employee KiwiSaver contribution on the bonus.
    - `student_loan` number, required: Repayment on the bonus. The whole bonus when the salary is already over the threshold, only the part above it when the salary is not.
    - `total_deductions` number, required: Everything taken off the bonus.
    - `net_bonus` number, required: What actually reaches the employee.
    - `crosses_bracket` boolean, required: True when the bonus straddles a tax bracket.
    - `top_bracket_reached` number, required: The marginal rate the top of the bonus reaches, as a percentage.
  - `disclaimer` string, required: Scope and limits of this calculation.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/calculate/apis/calculate-co-nz-api.md) · [All operations](https://skmtc.dev/calculate/apis/calculate-co-nz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/calculate/apis/calculate-co-nz-api/revisions/aa59a8e76614?raw)