Articles in this section

Including Advanced Tax-Related Merge Fields in Email Templates

Jann DiPaolo
  • Updated
Follow

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.

This article contains the following sections:

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:

  1. In the Email Template, expand the XERO TAX merge fields section.
  2. Click the Show Advanced button.
  3. 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.
  4. Click Add and the merge field is added to the Email Template. See also below for examples.

    1252_Xero_Tax_Merge_Advanced.gif

The following are the values for 'TaxType', 'Year' and 'Field' which can be selected or typed to make up the complete custom merge field.

TaxType

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)

Year

'Year' can be entered directly, for example, as 2020, 2019, 2018, etc.

 

Field

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

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

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 the data can be retrieved by FYI.

 

Related articles