---
title: "Secondary tax code for a second income, and the year-end position"
method: POST
path: "/v1/secondary-tax"
tags: ["Calculators"]
---

# Secondary tax code for a second income, and the year-end position

`POST /v1/secondary-tax`

## Request

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

Which secondary tax code a second income takes, and what it really costs.

A secondary code is not a penalty, and almost everyone asking believes it
is. It approximates the marginal rate the second income attracts on top of
the first, so roughly the right amount comes out through the year, and any
excess returns in the year-end square-up.

That is why `year_end_position` is part of the answer rather than an extra.
The flat rate matches the true marginal rate only while the second income
sits inside one bracket; the moment it straddles a boundary the flat rate is
charged on all of it and the difference comes back as a refund.

The rates look punitive because they are not income tax rates. Each carries
the 1.75% ACC earner levy inside it, and the SL variants add the 12% student
loan repayment on top, so 31.75% is 30 plus 1.75. The response takes the
rate apart into those components rather than making the caller do it.

The square-up covers these two income sources only. It knows nothing about
other income, donations, Working for Families or an existing tailored code,
so treat it as a direction and a rough size.

## Request body

- SecondaryTaxRequest
  - `main_income` number, required: Gross annual income from the main job.
  - `secondary_amount` number, required: The second income, in the frequency given.
  - `secondary_frequency` string: annual, monthly, fortnightly or weekly.
  - `has_student_loan` boolean: Whether a student loan is being repaid. This changes the code to its SL variant and adds 12 points to the flat rate.

## Response `200`

The IR330 code, what it deducts, and whether that leaves a bill or a refund.

- SecondaryTaxResponse
  - `result` SecondaryTaxResult, required
    - `main_income` number, required: Main job income as given.
    - `secondary_income_annual` number, required: Second income, annualised.
    - `total_income` number, required: Both together, which selects the code.
    - `tax_code` string, required: The IR330 secondary code: SB, S, SH, ST or SA, with SL if applicable.
    - `flat_rate_percent` number, required: The rate deducted from the whole second income.
    - `income_tax_component_percent` number, required: The income tax part of that rate.
    - `acc_component_percent` number, required: The ACC earner levy inside the rate. This is why a secondary rate is not comparable with an ordinary income tax rate.
    - `student_loan_component_percent` number, required: The student loan repayment part, zero without a loan.
    - `bracket` string, required: Combined income band the code comes from.
    - `secondary_paye` number, required: Deducted from the second income in a year.
    - `secondary_net` number, required: What is left of the second income.
    - `main_income_tax` number, required: Income tax on the main job.
    - `main_acc_levy` number, required: ACC levy on the main job.
    - `main_student_loan` number, required: Student loan on the main job.
    - `total_owed_on_combined` number, required: What is actually owed on both incomes together.
    - `total_deducted` number, required: What the two employers will have deducted.
    - `year_end_difference` number, required: Owed minus deducted. Positive is a bill, negative is a refund. A refund here is normal and is the answer to 'is secondary tax a rip off'.
    - `year_end_position` string, required: square, bill or refund.
    - `tax_year` string, required: Tax year the codes and rates are for.
  - `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)