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.
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 |