Getting Started

Overview

The Tax Traders Partner API gives your system three calculators for New Zealand tax payments: a payment deadline, a finance price and a provisional tax position. Each endpoint takes the figures you send and returns a result. No endpoint reads or changes any taxpayer’s data.

The API is for approved partners, such as accounting software providers and tax agents’ practice tools. Calls are machine to machine, authenticated with an OAuth 2 client credentials token.

Important: Results are estimates for illustration only. Pricing and dates can change. A figure returned by this API is not an offer, a quote or a confirmed transaction.

All paths are relative to /account/api/v2. Any other path returns 403 access_denied to partner clients. Each endpoint has its own article with full details.

Quickstart

You can make your first call in two steps: get a token, then call an endpoint with it. You need curl and jq.

1. Set your environment values. Tax Traders gives you the token URL, the API base URL and a client ID. Your client secret is sent separately.

2. Request a token and call the last payment date endpoint.
   

TOKEN_URL='<token URL>' API_URL='<API base URL>' # e.g. https://<host>/account/api/v2 CLIENT_ID='<client ID>' read -rs CLIENT_SECRET # paste the secret; it is not echoed # The credentials reach curl on stdin, so the secret never appears on a command line ACCESS_TOKEN=$(printf 'user = "%s:%s"\n' "$CLIENT_ID" "$CLIENT_SECRET" | curl -sSf -K - \ -X POST "$TOKEN_URL" \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=client_credentials&scope=tt-api-v2/calculators' | jq -er .access_token) unset CLIENT_SECRET curl -s "$API_URL/last-payment-date?tax_period=2026&balance_date=03-31" \ -H "Authorization: Bearer $ACCESS_TOKEN"

A successful call returns:

{ "payment_due_date": "2027-04-22" }

This script is for trying the API out. In production, use an OAuth 2 client library rather than shelling out to curl.

Authentication

Every call needs a bearer token from the OAuth 2 client credentials flow. Tokens last one hour; cache and reuse them.

Request a token

Send a POST to your token URL with HTTP Basic authentication (client ID as the user name, client secret as the password) and this form body:

The response is a standard OAuth 2 token response:

{ "access_token": "eyJ...", "expires_in": 3600, "token_type": "Bearer" }

Send the token

Include the token on every call:

Authorization: Bearer <access_token>

Send the bearer token only. Do not add other credentials or a client_id parameter; a request with one is rejected with 401 invalid_client_identifier.

Token lifetime

A token is valid for expires_in seconds (3,600 seconds, one hour). Cache it and reuse it for every call until shortly before it expires, then request a new one. Do not request a new token for each API call.

Keep credentials safe

• Keep the client secret on your server. Never put it in a browser, a mobile app or a source repository.

• Never log the client secret or access tokens.

• If you think the secret has been exposed, tell your Tax Traders contact straight away so it can be rotated.

Conventions

All requests go over HTTPS to your environment’s base URL, and all responses are JSON.

Personal information

The calculators need no personal information. Send only the fields listed for each endpoint. Do not include names, IRD numbers or any other identifier of a person or business.

Retries

On a 429 or 5xx response, retry with exponential backoff: wait 1 second, then 2, then 4, with at most 3 attempts. For 401 responses, see the Errors and glossary article.