Learn how to configure your APS Tax NZ software to start using Web Returns lodgement which replaces E-file for the Tax Year commencing April 2021. We also include steps on how to use Web Returns lodgement. 


General Information
Setup for Web Returns Lodgement

Using the Agent web page



General information


  • PM version 11.2 with cloud services enabled
  • APS Tax NZ 2021.Q1 or above  must be installed

The move to web-lodgement does not affect the creation, preparation, ledger-syncing and reporting of INC returns which remains in the desktop application for now. The new functionality for filing INC return types to IRD via Gateway services replaces the desktop functions that occur after a return’s preparation and sign-off has been completed. Instead of a ‘ready to lodge’ return being bundled and lodged to IRD via the E-File application, the return is instead transformed to web storage and new web application functionality provides management of the return’s lodgement via IRD’s ‘Gateway Services’.
To accommodate the delivery of this functionality, some small changes to the desktop software have occurred. Workflow status ‘Efile Lodged’ has been re-labelled ‘Ready To Lodge’ to align with Web workflow.

Expiration of E-File

The Tax NZ 2021.Q1 release has primarily focused on the development of INC returns lodging functionality via IRD Gateway services, as a replacement for E-file. Although E-file lodgement is still currently available via our software and via IRD’s E-file facility, will cease access in April 2021.
APS is ensuring all clients are ready to lodge all existing return types via Gateway Services prior to this time. At this stage web-based lodgement functionality will be optionally available. This means it will still be possible to continue using E-file for return lodgement until April 2021.


Setup for Web Returns Lodgement 

There are a few setup steps to work through to get started. 

Step 1 - Cloud services

The first step in setting up for Web Returns lodgement is to ensure that all your cloud services are running. 

1. Go to Windows > services when logged into your web server or server that has the services installed. 
2. Ensure that all APS services are running (APS Update service, APS Scheduling service,) 

  • The installed cloud-integration product NZTAX Return Updates can be viewed in Localhost: 7331/products 
  • The existing NZTAX TDS service now also performs a bulk tax-client on-boarding process if appropriate settings have been applied (see detail below).


Step 2 - Client On-boarding

The first step in setting up for Web Returns lodgement is to onboard clients to the web datastore. To activate the bulk client on-boarding function follow the steps below:

1. Go to APS > Tax Agent console > Details

  • Client Sync Status is initially set to

2. For each tax agent in the practice that has lodgement responsibility, edit the Client Sync Status to 1

  • Once the onboarding process is complete, the Client Sync Status will display the value of 2, to denote its completion.


- When Client Sync Status is set to 1, the on-boarding process is triggered to upload eligible clients linked to the chosen tax agent, from the practice SQL database to an APS web interface.
- Each client record is created in the secure APS web data store, ready to be linked to subsequently created web tax returns.
- This setting is per tax agent, so if you have multiple agents, each will need to be on-boarded separately.
- Only currently active clients will be on-boarded.
- The sync will run next time the automated Reckon Scheduling service runs (every 15 minutes), and may take some time to complete, depending on the number of clients and network speeds.
- Anyone already using GST or AIM web returns will already have those clients onboarded in this way.
- This onboarding this can be repeated at anytime by setting the sync status back to ‘1’ and waiting for the scheduling service to complete the process. However, this should not be necessary, since any changes are updated each time the return status is changed
- The onboarding process described above will also update any client records that have previously been onboarded to ensure latest details are included.


Step 3 - Switching to use Web Lodgement from e-file

In order to use Web Lodgement you need to set the system setting to True. Below are steps to complete this task

1. Go to APS > System and user settings > View > System > E-FILE  >Gateway Services Lodgement 

  • This is set to False by default to allow users to continue to use e-file until ready to switch. 

2. Set the True/False setting to True 


Using Web Returns Lodgement

Workflow: Return status

There are some changes in the workflow status of returns between E-File and Web Returns Lodgement, these are listed below

  • The status that indicated the return was ‘within the E-File process’ was labelled Efile Lodged. This status has been renamed Ready To Lodge, to indicate the return is available for lodgement via E-File or web Gateway Services integration.
  • INC return statuses in desktop remain  unchanged.
  • Web status progression commences with Approved status and goes as far as Lodged. Subsequent statuses (Assessed, Query/Hold, Closed) will be implemented later. When implemented, these web statuses will similarly be reflected in the desktop return.
  • Successful lodgement via Gateway Services results in the web return status being updated from Lodge-requested to Lodged, with the equivalent ‘IRD Confirmed’ status automatically set in the desktop return.

  • The text under Lodgement Method is amended from E-file to Web API. The return is now transformed and sent to the Web instead of creating a ‘blob’ for sending via the E-file application.


Step 4 - Tax agent/s linked to a user

Each APS tax user (Fee Earner) will only have tax agent context in the web page available for agents they are assigned to.

1. Go to Fee Earners > Details 
2. Assign one or more web-linked tax agent values to a chosen user (fee-earner).

  • Where more than one agent is assigned, the user can change tax agent context from a drop down list in the User popup accessed at top right of the Agent Web page. (see below)


Step 5 - Assign JOE rights for Tax agent page permissions

New JOE node Web Permissions has settings to control users’ access to the Agent pages and the actions available in them.
There are four agent page menu options available in the web-tax application.

  • Agent Details: ‘agent’ info, landing page
  • Agent TDS info: registration
  • Client Links: IRD tax type links for all clients
  • Returns: filtered list of all returns for agent’s clients

1. Go to System Administration consoles > JOE Administration > Tax Management > Web Permissions

2. Assign the appropriate JOE Rights as outlined in the table below. 

Joe Rights Web Access area
Agent Details Details for currently selected Tax Agent are displayed
Agent TDS Info TDS Link status is displayed
Agent TDS Link User can Link and Delink Tax Agent to IRD for TDS data collection
Agent Client Links Info Client IRD-Links info page is visible (tax types each client is linked to IRD for)
Agent Client Links Update Client Links can be updated to IRD (link or delink & mail redirection)
Agent Returns List Client tax returns (INC, AIM, GST) can be viewed in Agent Returns list
Agent Returns Lodgement Approved client returns can be lodged with IRD via Gateway Services


-By default, the Agent Details and TDS Info rights are enabled, this is to ensure that existing users who have been actively using Web GST and AIM returns lodgement are still able to do so, and are able to check their agent’s TDS setup status.
-TDS linking will have been already setup for your firm now and this would typically be done by a user with admin access. Granting access to the TDS Link option will allow that user to Link or Delink the tax agent’s TDS integration with IRD.


Step 6 - GST return ‘sync to desktop’ setting

When a web-GST return is created or it’s status changes, the change is now reflected back to the equivalent desktop GST return. If the desktop GST return does not exist, a ‘shell-placeholder’ desktop GST return can be created. A requirement when creating a desktop GST return is to link it to a matter and that matter is in turn linked to a ‘standard matter’ definition. In order for GST return creation to be automated, the standard matter linked to the GST return’s matter needs to be determined. This is achieved by setting a system SUPS parameter.

1. Go to Standard Matters, identify the ID for the standard matter you will use for auto-generated GST returns. In the example below, the desired standard matter’s ID is 119.

2. Go to System and user settings > NZTAX > GST Standard Matter ID.
3. Enter the ID from the identified GST standard matter.

Using the Agent web page

Accessing the Agent Web page

1. Go to Tax Agent > Web Page  click the Agent Web View button in the Tax Agent console

2. Log in if not already logged in.

  • This is the same username and password that will have been set up for all APS Cloud services applications.

Navigating the Agent Web page

The Agent web page contains the following functionality:

  • Tax Agent details (as above)
  • Transaction Data Service (TDS) Status.
  • Client IRD Links
  • Client Returns

Tax Agent Details

  • Tax Agent Details page shows current status (Active or Inactive), Agent name, IRD number, and Agent client list ID (which may or may not be the same as IRD Number).
  • It also shows any IRD Notifications that have received by that Agent. Notifications are discussed later in this document.

Transaction Data Services (TDS)

  • This page displays the IRD link status for this Tax Agent, the “Registered” status means the agent is correctly setup to receive TDS Transactional data from IRD.
  • This page is only used for linking or de-linking an agent with IRD.


Client IRD Links

  • Once clients have been onboarded via the process described earlier in this document, they will be made available to the Client IRD Links page. This page is to allow individual clients to be updated for the relevant tax types
  • You are able to update tax types for a client or multiple clients by selecting the field/s and click Submit.
  • Various filter options are available to allow sorting by Tax Type, Partner, Manager and a keyword search on Client names.
  • To use the search, begin typing the client name and then choose from the list of matches presented in the drop-down list.
  • Each entry can be refreshed individually to confirm that the latest information has been received from IRD.
  • Any errors will show a small red exclamation mark, which can be hovered over to display the actual error in a tooltip.


  • If you wish to register a client or clients to use all tax types, then Master option can be chosen, and in addition to the columns displayed, the last column shows a list where additional tax types can be chosen.
  • Update all clients is a resource-hungry action, so at present we will be restricting use of this option to once per week per user. It should not be necessary to perform this action often after initial setup.
  • If a client is not correctly set up for the required tax types, then returns may be rejected by IRD as a result. It is worthwhile spending time now to ensure these are correct.


Client Returns

  • To see the list of returns that have been set to Ready to Lodge, click the Client Returns option on the left menu:

Note that the default Return status is Approved. You may choose from the following filters as well:

  • Filter options are also available for Return Type, Tax Year, Period End Date and Client name (search option).
  • Selecting an item or items from the list is allowed depending on its status.
  • Items set to Approved, Lodge-Failed or Lodge-Requested can be chosen, Lodge button is then available.

  • Selecting all items in the current filter can be achieved by selecting the column header thus:

  • If a Calc date later than today’s date is present, then the return cannot be selected for lodgement until that date has passed. The calc date in this next example was edited prior to validating the return in the desktop software. This example was created on 17/08/2020 using a calc date of 28/08/2020, so although it can be Approved, it cannot yet be Lodged.

Lodging returns

1. Go to Client Returns
2. Select the return you want to lodge , click Lodge

  • This will send the chosen return(s) to IRD via Gateway Services. The status will change to Lodge-Requested for a short time after which time it will show as either Lodged, if it is successfully validated, or Lodge-Failed if there is a problem.
Note - Lodging a return via this method is the direct equivalent of lodging a return via the E-file Lodge Return function.

  • Once a return is successfully lodged, it is with IRD for processing, and you should later receive a Notification from IRD that it has been received (TBC). This is the e-file equivalent of receiving a confirmation.

3. Click the item entry to view the return details in client context. 

Viewing Web return status updates in the desktop

1. Go to Central Console > Tax Console > Return Selection page, the Tax Status column for each client will show the web returns status

  • Once the workflow status has been updated via the Web agent page, the desktop status for that return will also be updated. If the console page is already open, you will need to refresh this either by re-opening the page or using the Refresh button on the console menu.



  • Tax Manager is also updated in a similar manner.
  • These status columns will be kept updated constantly provided that the Reckon scheduling service is running. If you notice the status is incorrect, the first thing to check is that the cloud services are running correctly.

2. Go to Central console > Tax Console > Return Selection > select return > right click > Open Web Return to open the IRD Confirmed return 

  • The web page will then display the return.
  • Keypoints and amounts are not visible at this time, this functionality will be added at a later date, but this page can be used to check Return status, IRD status, and to perform Actions such as Prepop, Status check and Retrieve from IRD.
  • If other return types have been added for the selected client, they can be navigated to using the left hand menu. It is also possible to navigate to either the client context, or back to Agent context by click the name at the top.

Retrieving IRD notifications

IRD notifications can be retrieved on demand via the Agent and Client web pages

1. Go to Tax Agent > Web Page  click the Agent Web View
2. Login if required
3. Click the Request Update from IRD button.

  • These may contain confirmation of returns being received, notification of mail being received, or documents attached.

Agent context:


Client context:

1. Go to Tax Agent > Web Page  click the Agent Web View
2. Login if required
3. Select Client Returns 
3. Select Client
4. Click the Request Update from IRD button.

  • These may contain confirmation of returns being received, notification of mail being received, or documents attached.

IRD Notifications examples:

5. Enter a date range, this defaults to last 7 days.


Uploading and Downloading documents to IRD

  • Documents in support of a Tax Return may be uploaded to IRD post-lodgement. Once a return has been lodged successfully, a document may also be subsequently sent by IRD, eg a Statement of Earnings document.
  • Documents may be uploaded for submission to IRD.
  • This is a two stage process, the initial upload stores the chosen document in the APS Web Document Store. Once approved, the document can then be uploaded to IRD.


Upload a Document

  • Uploads can only occur in the return view if a return is lodged and IRD have sent an authentication token back.

1. Click the Upload Document button in Client or Return context.

  • In client context, documents can be uploaded linked to a return, or to a client, by selecting the appropriate option. If a return has been lodged already, the document may be assigned to that return, for example if IRD have requested more information. If the return has not yet been lodged, then any documents may be uploaded using the client option.

2. Enter a description

  • This may be useful if there are likely to be multiple documents to upload.
  • Once this is complete a message will display as below, your document is now saved to the APS Web Document store. 

Download a document

Once files are uploaded, or have been received from the IRD, they may be downloaded from the APS Web Document store for viewing locally. Documents may also be downloaded when in the Return context. 

1. Clicking the document icon on the far right of each entry.
2. Open the document from the download complete popup in your browser


Managing Uploaded documents

  • Documents in the APS web document store can be viewed, submitted to the IRD or deleted. Once uploaded, the document information popup is displayed.

1. Clicking the document icon on the far right of each entry will open the Document Information screen
2. Click 

  • View Document to open the document 
  • Submit to IRD to send the document to IRD

3. Check the I wish to delete this document checkbox to remove the document


  •  Once Submit to IRD has completed, a message is displayed to confirm success or failure.


  • If it transpires that the document previously uploaded was incorrect or needs to be re-submitted, there is also an option to invalidate the document with IRD.

4. Select the This document needs to be invalidated at the IRD checkbox if you need to re-submit or invalidate the document.

7.The final option is to Delete the document. Check the option I wish to delete this document to delete it from the document store.

  • This action will only remove the document from the local document store, and will not invalidate it with IRD. It is still possible to delete from document store, since documents lodged with IRD can be downloaded on request.

Client level view:

GST forms- Create Summary

In addition to being able to download and upload documents, it is also possible to create a GST Summary for GST returns. 

1. From the GST Returns page
2 Click the Create Summary button 

  • The GST Summary for period ended xxxx document is created

3. Go to the Document Icon and select View document to preview the document.

  • The summary is then previewed in its own browser window, information provided is similar to the GST summary generated by the desktop GST return console.
  • You may also Upload a document for a GST return, as well as create a GST Summary report.


IRD Activity Log Notifications

Any notifications received from IRD are also synchronised to the IRD Activity Log ribbon on the Compliance Admin page in PM. This page replaces the previous notifications for TAWS transactions (which are now obsolete).

The following types of notifications may be visible, depending on the information sent by IRD.

This information can be filtered by date and by Notification type:

  • ACTTDS refers to TDS transactions received
  • ACTSLF reports any lodge-failed returns
  • ADDCLI reports any missing client that has been added due to a notification being received for them. Note that these records are added only in the web returns database and not into the desktop application.

The remaining notification types are standard IRD notification types used per myIR webpage.

Related Products: APS TAX NZ
Comments (0)