# Calculate NZ contractor withholding and net payment

For a confirmed schedular contractor invoice, calculate the tax to withhold, the amount to pay the contractor and the filing and payment dates.

Canonical: https://aroai.com/tools/nz_contractor_withholding/

## Tool reference

MCP tool ID: `nz_contractor_withholding`. Availability: Live. Country: New Zealand.

Credit use: 1 credit.

## Input schema

```json
{
  "$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
}
```

## Example input

```json
{
  "tax_year": "2026-27",
  "activity_number": "1",
  "tax_residency": "resident",
  "invoice_total": 4600,
  "gst_registered": true,
  "gst_amount": 600,
  "rate_basis": "standard_activity",
  "payment_date": "2026-11-20"
}
```

## Usage notes

- 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.