Using Advanced Tax-Related Merge Fields

When creating an email template, you can include merge fields that are based on the tax information from Xero Tax. These are added from the merge field group "Tax".

Notes:

The Tax Merge Fields only work when the Xero Tax Integration has been established. The Xero Tax Settings must be configured to enable both "Import Tax Assessments" and "Consider Notices of Assessment Without Payable Date". Refer to Enabling Xero Tax Integration (Australia and New Zealand Only).
The notice of assessment fields are only generated when there is an Accepted/Agreed NOA in Xero Tax. Refer also to the Xero Help article Enter notice of assessment.
The Tax Merge Fields are used in the FYI pre-configured processes for Tax Assessments, which are triggered by Tax Returns and Assessments from Xero Tax (refer to Xero Tax Return AutoFile (Australia Only)). If these Tax Merge Fields are used in any other processes (such as Custom Processes) or if a template with the Tax Merge Fields is used when creating a new email, they will retrieve the data from the most recent Tax Return or Assessment.
The Tax Merge Fields only work after lodgement. They therefore cannot be used in a pre-lodgement email or document to inform clients what you estimate their tax position would be. There is no way FYI can retrieve the details unless the tax is lodged and accepted, and the only way to add the pre-lodgement estimate is to manually insert the figure.
Tax Return Merge Fields are not available for Activity Statements.

Adding the Tax Merge Field to an Email Template

Standard Merge Fields

To add a standard Merge Field to an Email Template:

In the Email Template, expand the Tax merge fields section.
Click the required field. For example, click Income to enter the merge field {{ TaxIncome }}.

Custom Merge Field

Values can be selected or manually typed in to make a custom merge field.

In the Email Template, expand the Tax merge fields section.
Click the Show Advanced button.
Enter each part of the merge field by selecting the Tax Type and Field from the drop-downs and typing the value required for the Year.
Click Add and the merge field is added to the Email Template. See also below for examples.

Merge Field	Details
Tax Type	The code that is shown for the 'TaxType' when the merge field is added is shown below in brackets. Australia Activity Statement (AS) Company Return (CTR) Income Tax (ITR) Partnership Return (PTR) Trust Return (TRT) SMSF (SMSF) New Zealand The TaxType is based on the ReturnType from the client. The code that is shown when the merge field is added is shown below in brackets. Trust and Estate's Income Tax Return (IR6) Non-resident Tax Return (IR3NR) Income Tax Return (IR9) Individual Income Tax Return (IR3) Partnership and Look Through Company (IR7) Companies Income Tax Return (IR4) Māori Authorities Income Tax Return (IR8) Personal Tax Summary (PTS)
Year	The 'Year' can be entered directly, for example: 2024 2023 2022, etc.
Field	The data provided by Xero is different depending on your location. Refer to your region below for a list of content available. Australia Estimated Income = amount of the estimated income tax Est. Payable/Refundable = amount of the estimated refund that is payable or refundable Income = amount of the income tax Income variance = amount of the variance from the estimate of the income tax Issue = date it was issued by the ATO Lodgement = date it was logged to the ATO Payable/Refundable = amount of the refund that is payable or refundable Payable/Refundable variance = the amount of the variance from the estimate of the amount payable or refundable Period from = from date of the period Period to = to date of the period State = state of the tax submission, that is, Draft, Filed, Completed New Zealand Period from = from date of the period Period to = to date of the period State = state of the tax submission, that is, Draft, Filed, Completed Please note that Xero does not send value data for Payable or Refundable for New Zealand practices.

The following are examples of how you can include these Merge Fields in an email template.

Your 2024 tax from {{ Tax_SMSF_2024_PeriodFrom }} to {{ Tax_SMSF_2024_PeriodTo }} is estimated to be {{ Tax_SMSF_2024_EstimatedPayableRefundable }}
Your 2024 income tax return from {{ Tax_ITR_2024_PeriodFrom }} to {{ Tax_ITR_2024_PeriodTo }} was lodged with the ATO on {{ Tax_ITR_2024_ Lodgement }}

Defaults for Year and Tax Type

When Tax Merge Fields are used in an email template, you can customise the Merge Field to different degrees of specificity with the Type and Year. For example:

{{ Tax_Income }}
{{ Tax_ITR_Income }}
{{ Tax_ITR_2024_Income }}

If the year or entity type parameters are not included in the Merge Field, they will default as follows:

Year - whatever is available for the most recent dataset of the relevant client
Entity Type - defaults to one of the following, as relevant for the client

ITR (Individual Tax Return)
CTR (Company Tax Return)
TRT (Trust Return)
PTR (Partnership Return)
SMSF (SMSF)

To add the Tax Merge fields so that defaults are applied, add them from the Advanced Tax section in the template and then delete parts of the field not required.

For example, instead of the full Merge Field of {{ Tax_ITR_2024_Income }}, editing the Merge Field to be {{ Tax_ITR_Income }} will default the year.

These defaults allow practices to avoid maintaining multiple versions of the same template. It also allows users to manually create emails that include tax merge fields in the event that there is an issue in an automation that uses the same template.

Archived Notice of Assessment

Data cannot be pulled through from a Notice of Assessment that has been archived. If you are not seeing the data for a Notice of Assessment, check the state. If it has been archived, change it to unarchived so FYI can retrieve the data.

Features