Calculate NZ contractor withholding and net payment.
LiveNew Zealand1 credit
What it does
For a confirmed schedular contractor invoice, calculate the tax to withhold, the amount to pay the contractor and the filing and payment dates.
Ask your AI
Calculate NZ contractor withholding and net payment. Ask me for any detail you need first, then show the result with its source and date, and list anything a person should check.
What comes back
You choose the rate basis (the standard activity rate needs a completed IR330C) and give the exact GST on a GST-registered invoice.
Good to know
- You choose the rate basis (the standard activity rate needs a completed IR330C) and give the exact GST on a GST-registered invoice.
- The payment date defaults to today, and payday filing, electronic filing and monthly PAYE payments are assumed unless you say otherwise.
- It does not decide worker status, residency or certificate validity.
For developers
| Tool ID | nz_contractor_withholding |
|---|---|
| Server | New Zealand |
| Credit behaviour | 1 credit |
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"tax_year": {
"type": "string",
"const": "2026-27"
},
"activity_number": {
"type": "string",
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27"
],
"description": "IRD IR330C activity number: 1 ACC personal service rehabilitation payments; 2 Agricultural land maintenance or development; 3 Agricultural, horticultural or viticultural labour contracts; 4 Apprentice jockeys or drivers; 5 Cleaning non-residential premises or equipment; 6 Insurance agents and sales commissions; 7 Company directors' fees; 8 Building industry labour-only contracts; 9 Demonstrating goods or appliances; 10 Resident entertainers; 11 Examiners' fees; 12 Fishing boat profit-share labour; 13 Forestry, bush work or flax work; 14 Freelance contributions to publications or productions; 15 Gardening, cutting or pest destruction for institutions; 16 Honoraria; 17 Modelling; 18 Visiting non-resident entertainers and professional sportspeople; 19 Labour-hire payments; 20 Caretaking, guarding, mail, milk, refuse or school transport; 21 Specified wild product sales; 22 Public office holders' fees; 23 Shearing or droving; 24 Resident television, video or film production work; 25 Voluntary schedular payments; 26 Non-resident contractor individual; 27 Non-resident contractor company. Choose the activity that the payer has confirmed applies."
},
"tax_residency": {
"type": "string",
"enum": [
"resident",
"non_resident_individual",
"non_resident_company",
"temporary_visa_holder"
],
"description": "User-confirmed contractor tax status. A temporary entry class visa holder uses the 15% elected-rate minimum. Only a non-resident contractor company uses the 20% no-notification rate."
},
"invoice_total": {
"type": "number",
"minimum": 0,
"maximum": 100000000,
"description": "Invoice total payable, including any GST charged."
},
"gst_registered": {
"type": "boolean",
"description": "Whether the contractor is GST registered."
},
"gst_amount": {
"description": "Exact GST charged on this invoice; required when gst_registered is true. Enter 0 if no GST is charged.",
"type": "number",
"minimum": 0,
"maximum": 100000000
},
"rate_basis": {
"type": "string",
"enum": [
"standard_activity",
"elected_rate",
"certificate_of_exemption",
"special_tax_rate",
"no_notification"
],
"description": "Required. Choose the basis confirmed by the payer: standard_activity only with a completed IR330C; elected_rate from that completed IR330C; certificate_of_exemption for a current IR331 that covers the payment; special_tax_rate from a current IRD tailored or special tax rate certificate; or no_notification when no completed IR330C was supplied. Activity 18 has a fixed 20% standard rate and no no-notification or elected rate. Activity 19 labour-hire payments cannot use a certificate of exemption."
},
"elected_rate_percent": {
"description": "Rate stated by the contractor on IR330C, from 10% to 100% for residents or 15% to 100% for non-residents and temporary-visa holders.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"special_tax_rate_percent": {
"description": "Rate on the contractor's current IRD tailored or special tax rate certificate; enter 0 when the certificate authorises no deduction.",
"type": "number",
"minimum": 0,
"maximum": 100
},
"payment_date": {
"description": "Optional payment date (YYYY-MM-DD). Defaults to today's NZ date when it falls in the supported year (2026-04-01 to 2027-03-31); otherwise required.",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"filing_frequency": {
"description": "Defaults to payday.",
"type": "string",
"enum": [
"payday",
"twice_monthly"
]
},
"filing_method": {
"description": "Defaults to electronic.",
"type": "string",
"enum": [
"electronic",
"paper"
]
},
"only_schedular_contractors_in_reporting_period": {
"description": "Set true only when this period contains schedular contractor payments and no other employees' pay. Defaults to false.",
"type": "boolean"
},
"paye_payment_schedule": {
"description": "Optional PAYE deductions schedule; defaults to monthly.",
"type": "string",
"enum": [
"monthly",
"twice_monthly"
]
}
},
"required": [
"tax_year",
"activity_number",
"tax_residency",
"invoice_total",
"gst_registered",
"rate_basis"
],
"additionalProperties": false
}Shared output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"anyOf": [
{
"type": "object",
"properties": {
"summary": {
"type": "string"
},
"data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"executionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"creditsCharged": {
"type": "number",
"minimum": 0
},
"usage": {
"type": "object",
"properties": {
"credits_charged": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"credits_remaining": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"credits_charged"
],
"additionalProperties": false
}
},
"required": [
"summary",
"data",
"creditsCharged"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
},
"usage": {
"type": "object",
"properties": {
"credits_charged": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"credits_remaining": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"credits_charged"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}
]
}