When creating a template for Word or Excel, you can include custom merge fields that are based on tax information from Xero Tax.
Note: The Tax Merge Fields can only be used in the FYI pre-configured processes for Tax Assessments which are triggered by tax returns and assessments (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 document, they will retrieve the data from the most recent Tax Return or Assessment.
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 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 Merge Fields are not available for Activity Statements.
- Xero Practice Manager Custom Merge Fields will only retrieve data from the Client, and not the Job.
Advanced Tax-Related Merge Fields in Word Templates
The structure of the merge field is as follows:
«Tax_'TaxType'_'Year'_'Field'»
The merge field is entered by typing it directly into the Word template using the Word Insert Field function (refer to Including Merge Fields in Word Templates and Stationery). It is added as a single Merge Field and includes the underscores. For example, «Tax_ITR_2020_Income» (see below for further examples).
The following are the values that can be used for 'TaxType', 'Year' and 'Field' which are entered to make up the complete custom merge field.
TaxType
SMSF = SMSF
ITR = Income Tax
AS = Activity Statement
CTR = Company Return
TRT = Trust Return
PTR = Partnership Return
Year
'Year' can be entered directly, for example, as 2020, 2019, 2018, etc.
Field
State = the state of the tax submission, that is, Draft, Filed, Completed
Lodgement = the date it was logged to the ATO
Issue = the date it was issued by the ATO
PeriodFrom = the from date of the period
PeriodTo = the to date of the period
EstimatedPayableRefundable = the amount of the estimated refund that is payable
PayableRefundable = the amount of the refund that is payable
PayableRefundableVariance = the amount of the variance from estimate of the refund that is payable EstimatedIncome = the amount of the estimated income tax
Income = the amount of the income tax
IncomeVariance = the amount of the variance from estimate of the income tax
Examples
The following are examples of how you can include these Merge Fields in a Word template.
Your 2020 tax from «Tax_ITR_2020_PeriodFrom» to «Tax_ITR_2020_PeriodTo» was lodged with the ATO on
«Tax_SMSF_2020_Lodgement»
Your 2020 tax from «Tax_SMSF_2020_PeriodFrom» to «Tax_SMSF_2020_PeriodTo» is estimated to be
«Tax_SMSF_2020_ 2020_EstimatedPayableRefundablet»
Refer also to the document FYI Merge Fields Comprehensive Guide
Downloading the FYI Merge Fields Comprehensive Guide
Click here to download the FYI Merge Fields Comprehensive Guide for a list of Merge Fields that you can copy and paste into your Templates and Stationery (or download the file from the bottom of this article).
Note: If you are using Chrome as your browser, the link may not automatically download the document. You need to right-click on the download link above, select Copy link address and paste it into a new browser tab in the browser's URL field.
Defaults for Year and Tax Type
When Tax Merge Fields are used in a template when manually creating a document, 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 following:
- 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)
These defaults allow you to set up templates with tax merge fields that can be used when creating documents via an automation or creating documents manually. This avoids having to maintain multiple versions of the same template. It also allows users to manually create documents that include tax merge fields in the event that there is an issue in an automation that uses the same template.
Advanced Tax-Related Merge Fields in Excel Templates
Merge Fields are added to Excel templates via Excel Name fields. They are added in the same way as standard Merge Fields, with FYI_ as the prefix. Refer to Including Merge Names in Excel Templates for details on defining Names in the Spreadsheet Template.
Merge Fields can also be added to Excel templates via Email codes. You can also set up the Advanced Tax-related Merge Fields in an Email Template and copy it into the Excel spreadsheet that will be used as the template. Refer to Including Merge Fields in Excel Templates and Including Advanced Tax-Related Merge Fields in Email Templates.
