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

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

The bill service provides the provisional tax assessment information held by Inland Revenue.

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

How the bill service works

By providing the ‘bill ID’ from a provisional tax assessment bill, the bill service will retrieve the information, ordered by provisional tax transaction, linked to that bill.

The version 1.0 release of this service is only available to digital service providers who have integrated with our transaction data services.

Software developer kit (SDK)

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

  • build pack
  • YAML file
  • sample request and response messages for each service operation (for each return type)
  • test scenarios
  • test data.

Bill 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 bill service

The gateway service used is the bill API. It provides the following capabilities through defined service operations:

Service operation Description
Post Retrieves provisional tax assessment information from Inland Revenue. Requires a Bill ID.

The information returned from a request can include:

  • Transaction information: customer, account period, bill, process date, filing period, due date, amount, method, transaction and whether reversed or not.
  • The provisional tax option used for the bill, and then the assessment: standard, estimate, ratio or AIM.
  • Percentages used for ratio options.
  • Return periods the standard option used for bill calculations (for example last period, the period before that) and the filing date.
  • Ratios used in the standard option: 110% for instalments until the return is filed, 105% for the remaining instalments.

The bill service business use case

The following is an example of a business use case on the gateway bill service operation that could be used to achieve a specific business outcome.

Number Use case Post
1 View the provisional tax assessment information 1

Supporting services

Identity and access services

Transaction data services