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 XERO TAX.
Notes:
- 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 processes 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; Activity Statement values are not synchronised to FYI.
This article contains the following sections:
- Adding the Tax Merge Field to an Email Template
- Available Merge Fields
- Defaults for Year and Tax Type
- Archived Notice of Assessment
Adding the Tax Merge Field to an Email Template
The structure of the custom merge field is as follows:
{{ Tax_'TaxType'_'Year'_'Field' }}
To add the Merge Field to an Email Template:
- In the Email Template, expand the XERO 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.
Available Merge Fields
Values can be selected or manually typed in to make a custom merge field.
TaxType
The data provided by Xero is different depending on your location. Refer to your region below for a list of content available.
Australia
The code that is shown for the 'TaxType' when the merge field is added is shown below in brackets.
- 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, as 2020, 2019, 2018, 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.
Examples
The following are examples of how you can include these Merge Fields in an email template.
Your 2020 tax from {{ Tax_SMSF_2020_PeriodFrom }} to {{ Tax_SMSF_2020_PeriodTo }} is estimated to be {{ Tax_SMSF_2020_EstimatedPayableRefundable }}
Your 2020 income tax return from {{ Tax_ITR_2020_PeriodFrom }} to {{ Tax_ITR_2020_PeriodTo }} was lodged with the ATO on {{ Tax_ITR_2020_ Lodgement }}
Defaults for Year and Tax Type
When Tax Merge Fields are used in a template when manually creating an email, you can add these with different degrees of specificity. For example,
{{ Tax_Income }}
{{ Tax_ITR_Income }}
{{ Tax_ITR_2021_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 change the fields in the body of the template by deleting parts of the field.
For example, instead of the full Merge Field of {{ Tax_ITR_2020_Income }}
- If you edit this to be {{ Tax_ITR_Income }} the year will default.
- If you edit this to be {{ Tax_Income }} the year will default and the type will default as relevant for the client.
These defaults allow you to set up templates with tax merge fields that can be used when creating emails via an automation or creating emails manually. This avoids having to maintain 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 of it. If it has been archived, change it to unarchived so FYI can retrieve the data.