---
title: "Add or remove NZ GST"
method: POST
path: "/v1/gst"
tags: ["Calculators"]
---

# Add or remove NZ GST

`POST /v1/gst`

## Request

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

Add or remove NZ GST (15%) from an amount.

`mode` decides which way round the amount is read. "add" treats it as
GST-exclusive and works out the GST on top; "remove" treats it as
GST-inclusive and works out how much of it is GST. Getting this backwards is
the usual source of a wrong answer: removing GST from $115 gives $100, while
taking 15% off $115 gives $97.75, which is not the same thing.

Every response returns all three figures regardless of mode, so the one you
need is always present.

`gst_rate` is overridable for historical work: GST was 12.5% before 1 October
2010. It has been 15% since.

## Request body

- GSTRequest
  - `amount` number, required: Dollar amount in NZD
  - `mode` 'add' | 'remove': 'add' treats amount as GST-exclusive; 'remove' as GST-inclusive.
  - `gst_rate` number: GST rate as a decimal. NZ standard 0.15 (15%).

## Response `200`

The amount split into its GST-exclusive, GST and GST-inclusive parts.

- GSTResponse
  - `result` GSTResult, required
    - `input_amount` number, required: The amount you sent, unchanged.
    - `gst_rate` number, required: Rate applied, as a decimal.
    - `mode` string, required: Whether GST was added or removed.
    - `amount_excl_gst` number, required: Amount before GST.
    - `gst_content` number, required: The GST portion itself.
    - `amount_incl_gst` number, required: Amount including GST.
  - `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)