Merge Tags

Dany Bouchard
Dany Bouchard
  • Updated

Overview

A merge tag is essentially a placeholder in your message template that gets replaced with real data when the message is sent out.

For instance, using a merge tag like {{firstName}} in your template will automatically insert the recipient's actual first name into each communication.

Guide: Customer communication

This article is part of a larger guide going over the concept of customer communication

Using merge tags

Some tags can be used across all system messages and custom communication, they are known as common tags, while system tags are limited to specific templates.
Learn more below.

To insert a merge tag inside a communication template, you can either type it out manually, or use the merge tag menu located inside the text toolbar. The toolbar appears when you edit a text element.

Using the merge tag menu is usually much easier and safer, since you will be provided a list of all the available tags for the current template.

merge_tags_button.png

Additionally, some tags have sub-elements you can access using the dot notation, like so: {{account.firstName}}.

Use the merge tag insertion menu described above to discover sub-elements linked to a merge tag.

 

Common tags

Common tags are available across all templates.

Category Merge tag Description
entity firstName Display the first name on the account.
entity lastName Display the last name on the account.
entity primaryEmail Display the primary email on the account.
entity gaiiaId The unique gaiia ID assigned to each account.
entity internetProvider Name of the internet provider assigned to each account.
entity billingAddress

The full billing address associated with the account. For example: 123 Fake Street, Toronto, ON L6H 1Y4. This is the "Physical Address" where the services are being provided at.

 

It is broken down into multiple different tags:

  • country -> The country associated with the address. Always shown as the 3-digit short form. For example, CAN for Canada or USA for the United States.
  • county -> (If applicable) The name of the county the address falls under
  • line1 -> The full address line (i.e. 123 Fake Street)
  • line2 -> (If applicable) The second line of the address
  • locality -> The city the address is located in
  • postalCode -> The postal or zip code of the address
  • premise -> The number in the address line
  • region -> The state/province
  • subBuilding -> If the account resides in an apartment or where there is more than one residence at an address, this can be used. For example, in the "15-123 Fake Street" or "123 Fake Street APT 15", "15" would be the subbuilding.
  • throughfare -> The name of the street in the address line
entity mailingAddress

If the account receives mail at an alternate address these merge tags can be used. This comes from the "Mailing Address" fields of the account.

It is broken down into multiple different tags:

  • country -> The country associated with the address. Always shown as the 3-digit short form. For example, CAN for Canada or USA for the United States.
  • county -> (If applicable) The name of the county the address falls under
  • line1 -> The full address line (i.e. 123 Fake Street)
  • line2 -> (If applicable) The second line of the address
  • locality -> The city the address is located in
  • postalCode -> The postal or zip code of the address
  • premise -> The number in the address line
  • region -> The state/province
  • subBuilding -> If the account resides in an apartment or where there is more than one residence at an address, this can be used. For example, in the "15-123 Fake Street" or "123 Fake Street APT 15", "15" would be the subbuilding.
  • throughfare -> The name of the street in the address line
entity primaryHomePhone The home phone number captured on the account.
entity primaryMobilePhone The mobile phone number captured on the account.
entity primaryWorkPhone The work phone number captured on the account.
entity referralCode The unique referral code associated with the account.
entity name If a value has been provided in the "Account name" field of account this merge tag can be used. This is often done if billing commercial customers who have a business name that needs to be tracked. 
admin primaryClientPortalLink The full URL of your client portal.
billing balanceDue

The current balance due of the account. This only includes outstanding balances on invoiced items.

Please note, this merge tag comes unformatted with the currency to allow for the creation of conditional logic based on an amount.

 

If displaying this just as a value, the following can be done to format it as a currency: {{billing.balanceDue | currency}} 
billing/lastInvoice dueDate

The current due date of the current invoice sent out to the account. This is usually the invoice sent for the current billing period.

 

This comes formatted as: YYYY-MM-DD. To change it to a MM/DD/YYYY format adjust the merge tag to the following: {{billing.lastInvoice.dueDate | shortDate}} 
billing/period start

The start date of the current billing period of the account.

This comes formatted as: YYYY-MM-DD. To change it to a MM/DD/YYYY format adjust the merge tag to the following:

{{billing.lastInvoice.period.start | shortDate}}
billing/period end

The end date of the current billing period of the account.

This comes formatted as: YYYY-MM-DD. To change it to a MM/DD/YYYY format adjust the merge tag to the following:

{{billing.lastInvoice.period.end | shortDate}}
billing availableFunds

If the account has any credits on the account, this merge field can be used to show it.

 

Please note, this merge tag comes unformatted with the currency to allow for the creation of conditional logic based on an amount.

 

If displaying this just as a value, the following can be done to format it as a currency: {{billing.availableFunds | currency}}
billing totalBalance

The overall balance of the account including both invoiced and uninvoiced transactions.

 

Please note, this merge tag comes unformatted with the currency to allow for the creation of conditional logic based on an amount.

 

If displaying this just as a value, the following can be done to format it as a currency: {{billing.totalBalance | currency}}

System tags

System tags are bound to specific templates and cannot be used outside of them.

Some templates detailed below might not be configured on your instance of gaiia.
This list is for reference only.

  • Merge tag Description Template
    accountGaiiaId The unique gaiia ID assigned to each account.
    • Service cancellation with equipment
    accountID The unique gaiia ID assigned to each account.
    • Return shipment created
    accountNumber The unique gaiia ID assigned to each account.
    • Expedition equipment and return procedure
    activationDate The date the services will be activated for the account. Formatted as: YYYY-MM-DD (example: 2024-01-09).
    • Move no technician request notice
    carrier The name of the carrier that will be delivering the shipment to the account. For example, FedEx. This is the carrier specified when submitting the shipment.
    • Sent shipment
    confirmationCode The unique code provided to the account to verify the account they created in the customer portal/checkout.
    • Cognito confirmation code
    currency Will display the type of currency within the template such as CAD or USD.
    • Reactivation
    • Return shipment first reminder
    • Return shipment second reminder
    customerName The first name of the customer associated with the account.
    • Activation appointment necessary
    • Activation convert to transfer
    • Activation no appointment necessary
    • Appointment completed
    • Appointment missed
    • Appointment modification completion
    • Expedition equipment and return procedure
    • Installation appointment confirmed
    • Installation appointment reminder
    • Invalid previous account name
    • Modem modification completion
    • Modem sent contact us notice
    • Move appointment confirmation
    • Move no technician request notice
    • Moving in no disconnection warning
    • New phone number completed
    • No tech activation initial
    • Outlet relocation appointment confirmation
    • Outlet relocation completion
    • Password changed
    • Phone portability confirmed
    • Reactivation
    • Return shipment completed
    • Return shipment created
    • Return shipment first reminder
    • Return shipment second reminder
    • Seasonal suspension
    • Sent shipment
    • Service cancellation with equipment
    • Service cancellation without equipment
    • Services activated
    • Speed modification completion
    • Transfer activation failed
    • Transfer activation initial
    • Transfer activation warning
    • With tech activation initial
    dueDate The date (shown as YYYY-MM-DD) that equipment part of the subscription must be returned by.
    • Return shipment created
    • Return shipment first reminder
    • Return shipment second reminder
    earliestInstallationTime When booking an appointment with a technician for services, the earliest time the technician will arrive.
    • Activation appointment necessary
    • Appointment modification completion
    • Installation appointment confirmed
    • Installation appointment reminder
    • Move appointment confirmation
    • Outlet relocation appointment confirmation
    equipmentWithPrices.0.name The name of the equipment associated with the account. When there is more than one piece of the equipment associated with the account, this represents the first piece of equipment in the list.
    • Return shipment first reminder
    • Return shipment second reminder
    equipmentWithPrices.0.price The price of the equipment associated with the account. When there is more than one piece of the equipment associated with the account, this represents the first piece of equipment in the list.
    • Return shipment first reminder
    • Return shipment second reminder
    equipmentWithPrices.0.quantity The quantity of the equipment associated with the account. When there is more than one piece of the equipment associated with the account, this represents the first piece of equipment in the list.
    • Return shipment first reminder
    • Return shipment second reminder
    equipmentWithPrices.1.name The name of the equipment associated with the account. When there is more than one piece of the equipment associated with the account, this represents the second piece of equipment in the list.
    • Return shipment first reminder
    • Return shipment second reminder
    equipmentWithPrices.1.price The price of the equipment associated with the account. When there is more than one piece of the equipment associated with the account, this represents the second piece of equipment in the list.
    • Return shipment first reminder
    • Return shipment second reminder
    equipmentWithPrices.1.quantity The quantity of the equipment associated with the account. When there is more than one piece of the equipment associated with the account, this represents the first piece of equipment in the list.
    • Return shipment first reminder
    • Return shipment second reminder
    formattedEquipments.0 The name of the equipment associated with the account. Where there is more than one piece of equipment associated with the account, this represents the first piece of equipment in the list.
    • Return shipment created
    formattedEquipments.1 The name of the equipment associated with the account. Where there is more than one piece of equipment associated with the account, this represents the second piece of equipment in the list.
    • Return shipment created
    hasPhoneService Returns a true/false regarding whether the account has phone service. A merge tag intended to be used as a condition to display/hide copy within the template.
    • Service cancellation with equipment
    • Service cancellation without equipment
    installationDate The date, shown as YYYY-MM-DD that the installation will occur on.
    • Activation appointment necessary
    • Appointment modification completion
    • Installation appointment confirmed
    • Installation appointment reminder
    • Move appointment confirmation
    • Outlet relocation appointment confirmation
    itemsInShipment.0.name The name of each item/equipment within the shipment. If there is more than one, multiple items can be displayed.
    • Expedition equipment and return procedure
    itemsInShipment.0.quantity The quantity of each item/equipment within the shipment. If there is more than one, multiple items can be displayed.
    • Expedition equipment and return procedure
    latestDisconnectionSubmissionDate When switching over to the new provider, this date (formatted as YYYY-MM-DD) provides details to the subscriber of when they need to cancel their services with their old provider.
    • Activation convert to transfer
    latestInstallationTime When booking an appointment with a technician for services, the earliest time the technician will arrive.
    • Activation appointment necessary
    • Appointment modification completion
    • Installation appointment confirmed
    • Installation appointment reminder
    • Move appointment confirmation
    • Outlet relocation appointment confirmation
    maxReactivationDate Following a planned suspension of services for a subscriber, this date represents (shown as YYYY-MM-DD) the last possible day they can keep their services suspended for.
    • Seasonal suspension
    maxSuspensionDurationInMonths Following a planned suspension of services for a subscriber, this represents the maximum possible length, in months, that a subscriber can keep their services suspended for. Just the numeric value is shown in the merge tag.
    • Seasonal suspension
    newPhoneNumber When a subscriber updates their phone number, this merge tag is used to display the new number. The merge tag provides the formatted phone number as: +1 (111) 111 - 1111.
    • New phone number completed
    portingActivationDate When a subscriber is moving their service from a previous provider, this merge tag provides them with the date it will be activate on your services (shown as YYYY-MM-DD).
    • Phone portability confirmed
    previousProviderDeactivationDate When a subscriber is transfer their services from a previous one, this merge field provides the date that they must deactivate their services on it (shown as YYYY-MM-DD).
    • Transfer activation initial
    previousProviderDeactivationDays When a subscriber is transfer their services from a previous one, this merge field provides how many days they have to deactivate their services with the old one. Shown as a numeric value.
    • Transfer activation initial
    provider When activating a subscribers services, should a different provider be used to offer the services, this merge field will allow you to specify the name of that provider so the subscriber is aware.
    • Activation convert to transfer
    refereeFirstName When an existing subscriber refers someone to you, this merge field displays the referee’s first name in the email (the one receiving the referral email).
    • Referral
    • Referral subscribed
    refereeLastName When an existing subscriber refers someone to you, this merge field displays the referee’s last name in the email (the one receiving the referral email).
    • Referral
    • Referral subscribed
    refererFirstName When an existing subscriber refers someone to you, this merge field displays the referrer’s first name in the email (the one sending the referral email).
    • Referral
    • Referral subscribed
    refererLastName When an existing subscriber refers someone to you, this merge field displays the referrer’s last name in the email (the one sending the referral email).
    • Referral
    • Referral subscribed
    referralCode When an existing subscriber refers someone to you, this merge field displays the referral code that can be entered at checkout to track a referral occurred and aware the appropriate subscribers.
    • Referral
    subscriptions.0.currency When services are being reactivated, this merge field provides the currency that the subscription price is in. For example, USD or CAD. In cases, where there is more than one subscription to display, 0 will always represent the first subscription in account is reactivating.
    • Reactivation
    subscriptions.0.name When services are being reactivated, this merge field provides the name of the subscription. In cases, where there is more than one subscription to display, 0 will always represent the first subscription in account is reactivating.
    • Reactivation
    subscriptions.0.price When services are being reactivated, this merge field provides the price of the subscription (with no currency). In cases, where there is more than one subscription to display, 0 will always represent the first subscription in account is reactivating.
    • Reactivation
    subscriptions.1.currency When services are being reactivated, this merge field provides the currency that the subscription price is in. For example, USD or CAD. In cases, where there is more than one subscription to display, 1 will always represent the second subscription in account is reactivating.
    • Reactivation
    subscriptions.1.name When services are being reactivated, this merge field provides the name of the subscription. In cases, where there is more than one subscription to display, 1 will always represent the first subscription in account is reactivating.
    • Reactivation
    subscriptions.1.price When services are being reactivated, this merge field provides the price of the subscription (with no currency). In cases, where there is more than one subscription to display, 1 will always represent the first subscription in account is reactivating.
    • Reactivation
    suspensionDate Following a planned suspension of services for a subscriber, this merge field represents the date that the services will be suspended on (formatted as YYYY-MM-DD).
    • Seasonal suspension
    tpiaDeactivationDate When a subscriber is transferring their services, in the event a disconnection cannot be completed with the current provider, this email is sent. The merge field provides the date (formatted as YYYY-MM-DD) that the subscriber must disconnect their services with their old provider in order to transfers them over.
    • Transfer activation warning
    trackingPin Went a shipment is sent to a subscriber (such as shipping a router), the merge provider allows a tracking code to be include in the email that is sent.
    • Sent shipment
    transferDate When a subscriber is activating their services, this merge provides the date that their services will be activated (formatted as YYYY-MM-DD).
    • Activation convert to transfer
    • Activation no appointment necessary
  • Merge tag Description Template
    account.firstName The first name associated with the account.
    • Credit card expiring
    • Delinquent - Overdue payment notice
    • Delinquent - Payment Arrangement
    • Delinquent - Suspension of services notice
    • Delinquent - Suspension of services within 24 hours notice
    • Manual statement
    • Overdue
    • Payment Successful
    • Payment due
    • Payment failed
    • Retry payment failed
    • Statement
    account.lastName The last name associated with the account.
    • Credit card expiring
    • Delinquent - Overdue payment notice
    • Delinquent - Payment Arrangement
    • Delinquent - Suspension of services notice
    • Delinquent - Suspension of services within 24 hours notice
    • Manual statement
    • Overdue
    • Payment Successful
    • Payment due
    • Payment failed
    • Retry payment failed
    • Statement
    accountNumber The unique gaiia ID assigned to each account
    • Statement
    amountDue The amount due that needs to be paid by the subscriber based on the current invoice period. This merge tag only includes the numeric value with no currency.
    • Delinquent - Overdue payment notice
    • Delinquent - Suspension of services notice
    • Delinquent - Suspension of services within 24 hours notice
    • Overdue
    • Payment due
    • Retry payment failed
    • Statement
    totalbalanceDue Displays the total balance owed by the account, including any outstanding balances that were carried forward. To format the value that is displayed in the templates as a currency, use {{totalBalanceDue | Currency}}.
    • Manual statement
    • Overdue
    • Payment due
    • Statement
    arrangement.0.amount Should an account have entered delinquency, and a payment arrangement has been decided upon, this merge tag provides the amount the account will pay in each instalment. Only the numeric value is shown without the currency.
    • Delinquent - Payment Arrangement
    arrangement.0.dueDate No description found
    • Delinquent - Payment Arrangement
    contactCustomerCareLimiteDate When an delinquent account is suspended, this merge field provides the last date (formatted as YYYY-MM-DD) the account has to address the overdue payment(s) before their services are disconnected.
    • Delinquent - Suspension of services notice
    daysBetweenNextAttempt Should a subscriber be setup for auto payments, an email is sent to them if payment could not be completed after it was retried. This merge field provides the how many days will elapse before payment is attempted again. Just the numeric value is provided for this merge field.
    • Retry payment failed
    dueInDays When a payment reminder email is sent to the account, this merge field can be used to specify how many days the account has remaining to pay their invoice. Just the numeric value is shown when this merge field is added to the template.
    • Payment due
    invoiceNumber This merge field display the unique number that is generated for each invoice in gaiia.
    • Statement
    lastPayment.formattedAmount Should a subscriber be setup for auto payments, an email is sent to them if payment could not be completed after it was retried. This merge field provides the amount the payment was for. It is formatted using currency as well. For example, CA$ 120.00.
    • Retry payment failed
    lastPayment.paymentMethodName Should a subscriber be setup for auto payments, an email is sent to them if payment could not be completed after it was retried. This merge field provides the payment method that failed. If a credit card was used the last 4 digits of it are also provided.
    • Retry payment failed
    minimumPaymentAmount When a customer enters delinquency, this merge field is used to display the minimum payment that must be made for an account to address it. This is formatted with the currency as well. For example, CA$20.00.
    • Delinquent - Overdue payment notice
    numberOfDaysNotice When a customer enters delinquency, this merge field is used to display how many days the account has to address the overdue payment before moving further in the delinquency process (such as suspension). Just the numeric value is shown.
    • Delinquent - Overdue payment notice
    paymentArrangementLimitDate When a customer enters delinquency, this merge field is used to display how the date the account has to address the overdue amount before moving further in the delinquency process. The format of the date is DD/MM/YYYY.
    • Delinquent - Overdue payment notice
    paymentMethod.maskedIdentificationNumber Should an account add a credit card to their account for payment and it is expiring an email is sent to them. This merge field provides the unique identification number to identify the payment method.
    • Credit card expiring
    paymentMethod.name This merge field provides the name of the payment method used. If displaying a credit card, the last 4 digits of the card are also shown.
    • Credit card expiring
    • Payment Successful
    • Payment failed
    suspensionHours No description found
    • Delinquent - Suspension of services within 24 hours notice
    suspensionDate Following a planned suspension of services for a subscriber, this merge field represents the date that the services will be suspended on (formatted as YYYY-MM-DD).
    • Delinquent - Suspension of services within 24 hours notice
    totalAmountDue When a payment is unsuccessful, this merge field can provide the amount the payment was for. The format of this merge field includes the currency as well. For example: CA$20.00.
    • Payment failed
    transaction.currency Can be used to provide the currency used in the payment. For example, CAD or USD.
    • Payment Successful
    • Payment failed
    transaction.formattedAmount Used to provide the payment amount. It is always formatted with the currency. For example: CA$20.00.
    • Payment Successful
    • Payment failed
  • Merge tag Description Template
    accountCreatedDate Used to indicate the date that the subscription will start. Formatted as MMMM dd, YYYYY. For example: December 12, 2013.
    • Initial order confirmation
    accountGaiiaId The unique gaiia ID assigned to each account
    • Initial order confirmation
    activationType Adds the type of activation the account needs, such as requiring an installing with a technician. More used to add conditional copy depending on activation.
    • Initial order confirmation
    clientPortalCreationLink Provides a unique URL for the account to create their account in the client portal.
    • Initial order confirmation
    firstName Display the first name on the account.
    • Initial order confirmation
    isOutletInstallationRequired A true/false merge field that provides details on whether the account needs to have outlet installation. More used to add conditional copy in the email than a direct merge field visible in the email.
    • Initial order confirmation
    isPortingNumber A true/false field that indicates whether the account is porting their number over. More used to add conditional copy in the email than a direct merge field visible in the email.
    • Initial order confirmation
    isReceivingNewNumber A true/false field that indicates whether the account is getting a new phone number. More used to add conditional copy in the email than a direct merge field visible in the email.
    • Initial order confirmation
    mailingAddress The full mailing address associated with the account. For example: 123 Fake Street, Toronto, ON L6H 1Y4.
    • Initial order confirmation
    needsCoaxialCable A true/false field that indicates whether the account needs a coaxial cable for their services. More used to add conditional copy in the email than a direct merge field visible in the email.
    • Initial order confirmation
    physicalAddress The physical address associated with the account where the services will be provided to. For example: 123 Fake Street, Toronto, ON L6H 1Y4.
    • Initial order confirmation
    provider When activating a subscribers services, should a different provider be used to offer the services, this merge field will allow you to specify the name of that provider so the subscriber is aware.
    • Initial order confirmation
    supportLink Allows you to include a link to accounts to contact support.
    • Initial order confirmation
    transferDate When a subscriber is activating their services, this merge provides the date that their services will be activated (formatted as YYYY-MM-DD).
    • Initial order confirmation
    transferDeadlineDate If an account is transferring their services over, the date the account must cancel their services with their old provider. Formatted as YYYY-MM-DD.
    • Initial order confirmation
  • Merge tag Description Template
    tenant.id When generating tickets through the ticket system, this merge field will display the unique id of your gaiia instance.
    • Ticket assignation
    • Ticket status update
    tenant.slug When generating tickets through the ticket system, this merge field will display the slug of your gaiia instance. Usually, your business name without any spaces or capital letter.
    • Ticket assignation
    • Ticket status update
    tenant.name When generating tickets through the ticket system, this merge field will display the name of your gaiia instance. Usually, your business name.
    • Ticket assignation
    • Ticket status update
    ticket.id When generating tickets through the ticket system, this merge field will display the unique id of the ticket that was created/updated.
    • Ticket assignation
    • Ticket status update
    ticket.readabledID When generating tickets through the ticket system, this merge field will display the a more client-friendly id to the account and the one that is also displayed in their portal.
    • Ticket assignation
    • Ticket status update
    ticket.status When generating tickets through the ticket system, this merge field will display the current status of the ticket.
    • Ticket status update
    user.firstName When generating tickets through the ticket system, this merge field will display the first name of the user who the ticket was assigned to or updated by.
    • Ticket assignation
    • Ticket status update
    user.id When generating tickets through the ticket system, this merge field will display the id of the user who the ticket was assigned to or updated by.
    • Ticket assignation
    • Ticket status update
    user.lastName When generating tickets through the ticket system, this merge field will display the last name of the user who the ticket was assigned to or updated by.
    • Ticket assignation
    • Ticket status update
    fromUser.firstName When a reply is posted on a ticket, this merge field will display the first name of the replier.
    • Ticket status update
    fromUser.lastName When a reply is posted on a ticket, this merge field will display the last name of the replier.
    • Ticket status update
    fromUser.email When a reply is posted on a ticket, this merge field will display the email of the replier.
    • Ticket status update

Related to

Was this article helpful?

Have more questions? Submit a request