Skip to main content
Check out our new content, navigation and design for digital service providers.

COVID-19 - Level 1 If you've been affected by COVID-19, we may be able to help. Find out more

We're prioritising digital service providers whose design solutions make it easy for end users to meet their tax obligations and receive their social policy entitlements. We'll contact you to discuss how your software achieves this before we start any gateway services integration.

The prescribed investor rate (PIR) calculator service provides a suggested prescribed investor rate for an individual customer.

If you have any questions about the PIR calculator service or using gateway services for the PIR calculator service, email GatewayServices@ird.govt.nz

How the PIR calculator service works

Income from PIE (portfolio investment entity) investments is taxed at a rate called the prescribed investor rate or PIR.

Because PIRs are chosen when a customer opens an account but the tax is squared up at a later date, the PIR may be out of date. The PIR calculator service can assist in this scenario by providing a suggested prescribed investor rate for an individual customer.

The customer in consultation with their PIE provider is responsible for using the correct prescribed investor rate.

Software developer kit (SDK)

View and download the PIR calculator service software developer kit  to help you integrate:

  • sample request and response messages
  • the Open API YAML file
  • the build pack that provides the data definitions for the request and response messages
  • test scenarios
  • test data.

PIR calculator service software developer kit (SDK) on GitHub


Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.

Getting started guide

Gateway service capability for the PIR calculator service

The gateway service is the PIR calculator service API. It provides the following capabilities through a defined service operation:

Service operation Description
Post Retrieves a customer's suggested prescribed investor rate from Inland Revenue.

The identity attributes that need to be supplied are:

  • the individual investor's IRD number
  • the PIE's IRD number
  • the investor’s name, date of birth and address (only for non-KiwiSaver PIEs)

PIR calculator service business use cases

The following are examples of sequences of the gateway PIR calculator service operations that could be used to achieve a specific business outcome. The numbers for each use case are the order in which these operations should be called when using this services.

Number Use case Post
1 View a customer's prescribed investor rate 1

Supporting services

Identity and access