Skip to main content

Delays to response times: It's taking longer than usual to answer calls and myIR messages, including for unclaimed money. You may be able to use self-service options in myIR. You can also find information on our website by typing in what you want to do in the search bar. Thank you for your understanding. Log in to myIR

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 [email protected]

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 information

Identity and access services 

Managing myIR logons and gateway services access tokens

Jump back to the top of the page