---
title: "Withholding tax on a schedular payment to a contractor"
method: POST
path: "/v1/schedular-payments"
tags: ["Calculators"]
---

# Withholding tax on a schedular payment to a contractor

`POST /v1/schedular-payments`

## Request

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

Work out the withholding tax on a contractor payment.

Two rules cause most of the trouble here.

The first is that withholding tax is charged on the payment EXCLUDING GST.
A GST registered contractor invoicing $1,000 plus GST bills $1,150, and the
withholding is charged on the $1,000, not the $1,150. Charging it on the
GST-inclusive figure over-deducts by 15% of the tax every time.

The second is that the rate depends on the activity, not on the contractor.
Schedule 4 of the Income Tax Act sets a standard rate for each listed
activity, and a contractor may elect a different rate between 10% and 40%
on an IR330C. Without that form the payer must deduct at 45%, the
no-notification rate, which is punitive by design and catches people who
simply never sent the paperwork back.

The deduction is not a final tax. It is a credit against the contractor's
income tax for the year, so a contractor with deductible expenses usually
gets some of it back, and one with a large profit usually owes more.
`year_end_credit` is the figure that goes in the return.

## Request body

- SchedularPaymentRequest
  - `payment_excluding_gst` number, required: The fee BEFORE GST. Withholding tax is charged on this, never on a GST-inclusive figure.
  - `activity` 'company_directors' | 'public_office' | 'sports' | 'commission' | 'entertainers_resident' | 'modelling' | 'cleaners' | 'forestry' | 'horticultural' | 'shearers' | 'labour_hire' | 'entertainers_non_resident' | 'standard_default': Schedule 4 activity, which sets the standard rate.
  - `rate_option` 'standard' | 'nominated' | 'no_form': 'standard' uses the Schedule 4 rate, 'nominated' a rate elected on the IR330C, 'no_form' the 45% no-notification rate.
  - `nominated_rate_pct` number, nullable: Elected rate as a percentage, 10 to 40. Required when rate_option is 'nominated'.
  - `gst_registered` boolean: Whether the contractor is GST registered, in which case GST is added and received.

## Response `200`

Invoice, the tax the payer deducts, and what the contractor is left with.

- SchedularPaymentResponse
  - `result` SchedularPaymentResult, required
    - `payment_excluding_gst` number, required: The fee the withholding is charged on.
    - `gst_added` number, required: GST added to the invoice, if registered.
    - `gross_invoice` number, required: What the invoice totals.
    - `withholding_rate` number, required: Rate applied, as a decimal.
    - `withholding_tax` number, required: Tax the payer deducts and sends to Inland Revenue.
    - `net_to_contractor` number, required: What lands in the account: fee less withholding plus GST.
    - `year_end_credit` number, required: The withholding is a credit against the year's tax, not a final tax.
    - `rate_basis` string, required: Why that rate applies.
    - `warning` string, nullable: Anything worth acting on, such as a missing IR330C.
    - `inputs` object, required: The inputs used, with defaults filled in.
  - `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)