---
title: "When an employer must pay PAYE and file the pay run"
method: POST
path: "/v1/paye-due-dates"
tags: ["Calculators"]
---

# When an employer must pay PAYE and file the pay run

`POST /v1/paye-due-dates`

## Request

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

Work out the two employer PAYE deadlines for a pay date.

PAYING and FILING are different deadlines and missing either has its own
consequences.

Payday filing is due within TWO WORKING DAYS of the payday itself. The
payment is due on the 20th of the following month for a monthly payer, or on
the 20th and the 5th for a twice-monthly payer.

Which payer you are is decided by PAYE PLUS ESCT sent to Inland Revenue over
the prior twelve months, not by the size of the payroll and not by headcount.
The threshold is $500,000 of deductions. A business paying $2m in wages is
usually still a monthly payer, so guessing from turnover gets it wrong.

Both dates shift off weekends and national public holidays, including
Mondayised ones. Where a shift happened, `payment_due_shifted_from` and
`payday_filing_due_shifted_from` show the date it moved from, so the answer
can be checked rather than taken on trust. Regional anniversary days do not
move a PAYE date and are deliberately excluded.

`paper_filing_due` is returned every time because paper filers work to a
different rule, ten days from the end of the month.

## Request body

- PayeDueDatesRequest
  - `pay_date` string, required: The date employees are paid, ISO format YYYY-MM-DD. The payday, not the period end.
  - `annual_paye_and_esct` number: PAYE plus ESCT sent to Inland Revenue over the prior 12 months. Above $500,000 means twice-monthly.
  - `electronic_filer` boolean: Electronic filers have two working days. Paper filers have a different deadline.

## Response `200`

Both deadlines, and what a weekend or public holiday moved them from.

- PayeDueDatesResponse
  - `result` PayeDueDatesResult, required
    - `payer_type` string, required: 'monthly' or 'twice_monthly'.
    - `payer_reason` string, required: Why that applies, against the $500,000 threshold.
    - `pay_date` string, required: The payday given.
    - `payment_due` string, required: When the PAYE must reach Inland Revenue.
    - `payment_due_shifted_from` string, nullable: The original date, if a weekend or public holiday moved it.
    - `payday_filing_due` string, required: When the pay run must be filed. A separate deadline.
    - `payday_filing_due_shifted_from` string, nullable: The original filing date, if it was moved.
    - `paper_filing_due` string, required: Deadline for paper filers, ten days after month end.
    - `period` string, required: Which pay period this payment covers.
    - `inputs` object, required: The inputs used, with defaults filled in.
  - `disclaimer` string, required: Scope and limits of these dates.

## 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)