Collapse Menu
Docs Home
Extensibility Options
Contact Support

Template Reference

Overview

This article provides additional details about modifying the templates used for Customer Notifications.

The Customer Notifications feature allows you to customize the email messages that FastSpring automatically sends to customers when certain events occur. For example, you can customize the message sent to customers after each successful purchase.

The content of the messages sent via a customer notification is generated based on the notification's template. To begin editing the template for a notification, click the TEMPLATE command, as shown below.

You can edit the subject line used for messages sent via the notification by making changes to the Subject field of the template. You can edit the body of the messages by modifying the HTML and Text tabs of the template's message body area.

If you make a mistake entering one of the template elements, such as a variable for an order object or some invalid HTML code, the green Valid indicator next to the HTML tab changes to a red Invalid indicator. You cannot save your changes while the Invalid indicator appears. In the example below, the shared snippet {{header2}} is included in the template. However, that is not a valid tag because no such shared snippet has been defined in this example.

The Test link lets you send a test message to a specified email address with your current changes before saving them. Using the Test link allows you to see how the messages will look without committing the changes to be used for live customer orders. If you send a test message, be sure to review it carefully in your email client before you click  to commit your changes.

Each notification's template consists of basic HTML and CSS code, combined with certain other elements. You can use these proprietary elements to render order-specific data and streamline the process when editing a template to customize the messages.

You can think of each of those other elements as belonging to one of four classifications:

 

Logical Evaluation Elements

Logical evaluation elements let you display specific sections of content within a notification conditionally. For example, you could include text, HTML, or shared snippets conditionally based on whether or not a particular product is in the order.

Here are examples of some commonly-used logical evaluation elements.

Element

Description

Example

Explanation

{{#each}}

Requires an order object reference (e.g. order.items) and a closing {{/each}} tag.

Cycles through all objects of the specified type, processing the contents up to the closing {{/each}} tag for each.

{{#each order.items}}
{{display}}
{{/each}} 

This example loops through each product included in the purchase (order.items). Any content included between {{#each order.items}} and {{/each}}, such as the variable {{display}} that renders the product's display name, is evaluated and processed for each product in the order.

{{#if}}

Conditional evaluation for use in Boolean expressions.

This element requires a closing {{/if}} tag.

You can use this with object references to control when specific behavior occurs or when certain content appears in the messages.

{{#if license}}
{{display}}: {{license}}
{{/if}}

This example, paraphrased from the Default Order Receipt, is found in the context of an {{#each fulfillments}} loop. For each fulfillment action associated with a product, this checks to see whether or not the fulfillment action is a license key.

If the fulfillment action is a license key, the product's display name is rendered in place of the {{display}} variable, and the license key is rendered in place of the {{license}} variable.

If the fulfillment action is not a license key, nothing between this {{#if}} and its closing {{/if}} tagis rendered.

{{#iff}}

Conditional evaluation for use in comparisons, such as checking for a specific string variable or other value and then reacting to the result of that check.

Requires a closing {{/iff}} tag.


You can optionally use an {{else}} tag to handle the reverse outcome (i.e., when the result of the {{#iff}} evaluation is false.)


You can use this with object references to control when specific behavior occurs or when certain content appears in the messages.

The following operators are supported for use with {{#iff}}be sure to include double-quotation marks around the operator in your expression, as in the example shown to the right: 

==

equal to

!=

not equal to

less than

greater than

<=

less than or equal to

>=

greater than or equal to

{{#iff product "==" "example1"}}
{{>Example1AP}}
{{else}}
{{>productAP}}
{{/iff}}

This example, which you would implement in the context of an {{#each order.items}} loop, checks whether the current product path is equal to the string "example1".

If that expression is true - i.e., when "example1" is the product path of the current item in the product loop - a custom shared snippet named Example1AP is inserted.

If that expression is false - i.e., when "example1" is NOT the product path of the current item in the product loop - a custom shared snippet named productAP is inserted.

You could also insert text or HTML directly into your comparison, but using shared snippets might be quicker, cleaner, and more efficient. Your shared snippet can include all translations and even other shared snippets.

 Tip

The above is only one example of how you can use comparisons; another use might be to suppress or hide certain parts of the email message conditionally. You would not even have to use an {{else}} condition in some cases.

Nor is the product loop the only place you can use comparisons like this. This feature allows for a great deal of customization and flexibility.

back to list

 

Object References

You can include references to order or subscription elements in the notification. The following are some examples of elements you can include:

  • the list of products in an order
  • the customer's name and email address
  • license keys issued for an order

To inject these references into the template, insert a variable consisting of curly brackets and the object's name. For example, including the variable {{order.reference}} in the body of your notification renders the order reference (order number) in the email messages. The key to taking advantage of object references is to know the correct variable names.

 Note about variable names and HTML escaping

The double 'Handlebar' format used to insert object reference variables also causes all characters to be HTML escaped. Therefore, if your product names include certain punctuation such as a single quote character ('), you should use triple 'Handlebars' instead, to disable the HTML escape functionality.

For example, if your subscription product name has a single quote character, you can change {{subscription.display}} to {{{subscription.display}}} so that the character (') will be rendered rather than the corresponding HTML encoding (&#x27;).

Many of the objects are subordinate to other objects. Therefore, you have to include the name of the containing object as well as the name of the actual field you want in a single variable for it to work correctly. For example, the correct variable name for the order's subtotal is {{order.subtotal}} as opposed to just {{subtotal}}. As another example, the correct variable name for your customer support email address as configured in your Store is {{store.support.email}}. Entering only {{support.email}} does not work.

The JSON data output for an order event uses arrays to group fields that may have more than one value in a single purchase transaction. For example, since an order may include more than one product, the system uses an "items" array to group all products in the order record. As a result, you can only include certain variables inside the context of an {{#each}} loop. For example, since you do not know in advance which specific products will be included in any given purchase transaction, the {{#each.order.items}} element is needed to "loop" through all products that were purchased. Inside that loop, it is not necessary to specify the containing array objects in your variable names. Each variable you include in the loop will be evaluated once, separately, for each item in the array (e.g., order items). For example, between {{#each.order.items}} and its corresponding {{/each}}, you can include things like {{display}} to render the display names of all products that were purchased, like this:

{{#each.order.items}}
    {{display}}
{{/each}}

The following table identifies some of the order objects that you can include in your notification template.

Object

Type

Description

order.to

general

email address to which the notification message is being sent

order.replyTo

general

your reply email address, as configured under Settings > Store Settings >
General > Reply-To Email (typically should be your customer service
address) 

order.language

general

two-character ISO language code for the language in which the transaction was
processed (e.g. "en") 

order.reference

general

order reference

order.account.url

general

URL for the customer-facing Account Management page associated with this customer 

order.changedDisplay

general

the date on which the transaction record was most recently modified, formatted as
MM/DD/YYYY; in the context of the Default Order Receipt notification template,
this is the order date

example:

06/26/2020 

order.live

Boolean

indicates whether or not the order was live (as opposed to a test order)

order.currency

general

3-character ISO code for the currency in which the transaction was processed

order.total

number

total price paid by the customer, without currency indicator

order.totalDisplay

general

the total price paid by the customer, formatted to include currency indicator

order.tax

number

amount of sales tax or VAT paid by the customer (if any), without currency indicator

order.taxDisplay

general

amount of sales tax or VAT paid by the customer (if any), formatted to include currency
indicator

order.subtotal

number

order subtotal before sales tax or VAT (if any), without currency indicator

order.subtotalDisplay

general

order subtotal before sales tax or VAT (if any), formatted to include currency indicator

order.account

general

account ID of the customer

order.discount

number

amount of the discount applied to the order (if any), without currency indicator

order.discountDisplay

general

amount of the discount applied to the order (if any), formatted to include currency
indicator

order.discountWithTax

number

amount of the discount applied to the order (if any) including any sales tax or VAT,
without currency indicator

order.discountWithTaxDisplay

general

amount of the discount applied to the order (if any) including any sales tax or VAT,
formatted to include currency indicator

order.invoiceUrl

general

URL for the customer's invoice for this transaction

order.billDescriptor

general

transaction description that will appear on the customer's payment account

example:

FS *  fsprg.com

order.payment.type

general

indicates the method of payment used by the customer (e.g., "card")

order.payment.cardEnding

general

indicates the last four digits of the card number used for the purchase, where
applicable

order.tags

general

renders the values for any order-level custom tags that were associated with the
purchase (e.g., for Custom Orders or orders created using POST /orders via the
FastSpring API).

Enter the key name for the tag whose values you want to appear in email messages.

For example, if one or more orders may have a custom tag with a key name of
REFERRALMETHOD, you could render the values for that tag in email messages
by including the following in your notification template:

{{order.tags.REFERRALMETHOD}}

order.customer.company

general

company name entered by the customer, if any

order.customer.email

general

customer's email address

order.customer.first

general

customer's first name

order.customer.last

general

customer's last name

order.customer.phone

general

telephone number entered by the customer, if any

order.address.addressLine1

general

customer's address line 1 for orders with a physical product or required
shipping address 

order.address.addressLine2

general

customer's address line 2 (if any) for orders with a physical product or required
shipping address 

order.address.city

general

customer's city for orders with a physical product or required shipping address

order.address.region

general

customer's state, province or region for orders with a physical product or required
shipping address 

order.address.country

general

customer's country as specified in the address for orders with a physical product or
required shipping address 

order.address.postalCode

general

customer's postal code for orders with a physical product or required shipping
address 

order.items

array

array consisting of various fields of product information for the products that have
been purchased in this transaction

usage example:

{{#each order.items}}

{{display}}

{{/each}}

 product

general 

product path for the current order item

only valid in the context of {{#each order.items}} ... {{/each}}

 quantity

number 

quantity of the current order item that was purchased

only valid in the context of {{#each order.items}} ... {{/each}} 

 display

general 

display name for the current product

only valid in the context of {{#each order.items}} ... {{/each}}

 subtotal

number 

subtotal for the current order item

only valid in the context of {{#each order.items}} ... {{/each}}

 sku

general 

sku (if any) from the product record of the current order item

only valid in the context of {{#each order.items}} ... {{/each}} 

 attributes

general

custom attributes (if any) from the product record for the current order item

Enter the key name from the product's custom attribute that you want to appear,
e.g., as configured under Products > More > Custom Attributes > Key. The
corresponding value is rendered in the email messages.

For example, if one or more of your products has a custom attribute with a Key of
OLDSKUID and each of your products has a unique value for that property,
you could render those values in email messages by including the following in
your notification template:

{{attributes.OLDSKUID}}

only valid in the context of {{#each order.items}} ... {{/each}}

 discount

number 

discount (if any) applied to the current order item, without currency indicator

only valid in the context of {{#each order.items}} ... {{/each}}

discountDisplay

general

discount (if any) applied to the current order item, formatted to include currency
indicator

only valid in the context of {{#each order.items}} ... {{/each}}

 subscription.id

general 

subscription ID (if any) associated with the current order item

only valid in the context of {{#each order.items}} ... {{/each}} 

 coupon

general 

coupon code of any promotion applied to the current order item

only valid in the context of {{#each order.items}} ... {{/each}} 

fulfillments

array

array consisting of various fulfillment-related fields (if any) applicable to the
current product

Your template needs to use a nested loop called 'this' within the {{#each.fulfillments}}
loop, as illustrated here:

{{#each fulfillments}}

{{#each this}}

((your fulfillment variables go here))

{{/each}}

{{/each}} 


only valid in the context of {{#each order.items}} ... {{/each}} 

type

general

type of the current fulfillment action, for the current product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

display

general

display name indicating the type of the current fulfillment action for the current
product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

For example:

for a download, this will render file
for a license key, this will render License Key.

license

general

license key (if any) issued for the current fulfillment action, for the current
product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

size

number

size of the download file associated with the current fulfillment action (if any),
for the current product, in bytes

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

file

general

download URL for the file (if any) associated with the current fulfillment action,
for the current product

only valid in the context of {{#each fulfillments}}{{#each this}} ... {{/each}}{{/each}}

order.support.contactName

general

your support contact name, as configured under Settings > Store Settings >
Support Contact > Support Contact Name

order.support.contactEmail

general

your support contact email address, as configured under Settings > Store Settings
Support Contact > Support Contact Email 

order.isRebill

Boolean

A Boolean value indicating whether or not the transaction was processed as an automatic
rebill on an existing subscription

New orders placed directly by customers have a value of false for this item.

 

back to list

 

Shared Snippets

Shared snippets are self-contained, commonly-used elements of notifications that can be used by more than one notification. For example, inserting the {{>header}} tag in the body of your notification causes the entire contents of the {{>header}} snippet to be rendered in place of the {{>header}} tag. This method allows you to create a single message header with images, links, and company information. You can then use that header in multiple notification templates without having to recreate it in each one. Later on, if you need to make changes to the header, you can modify the shared snippet. All notifications that use that snippet will automatically use the current version of it.

In addition to your notifications' templates, you can also use shared snippets inside other shared snippets. You define shared snippets on the Shared Snippets page of the Customer Emails tab.

The following shared snippets are available by default.

Snippet Variable

Description

{{>border-style}}

Specifies border width, type, and color; you can use this in a border attribute in place of entering inline styling (similar to a class in a style sheet).

{{>font}}

Specifies a series of font families; you can use this in a font-family attribute place of a list of font families.

{{>footer}}

Provides a block of HTML and CSS, with some translations and other shared snippets, designed to render a professional-looking footer for use at the bottom of your templates.

{{>header}}

Provides a block of HTML and CSS, with some translations and other shared snippets, designed to render a professional-looking header for use at the top of your templates.

{{>header-background-color}}

Specifies the hex value of a color (#30363d by default) that is used in the {{>header}} snippet, by default, to color the header background. You can also use this in any color attribute in your template, or another shared snippet.

{{>logo}}

Specifies the URL for a logo file (http://fastspring.com/images/fastspring-orange-white-logo.png by default). You can use this in the src attribute of an img element in your template or in another shared snippet.

 Tip

For best results, we recommend using a logo image no wider than approximately 275 pixels. The default logo image is 143 x 35 pixels.

{{>store-title}}

A simple string of text that identifies the name of your Store. This snippet appears within the {{>text-header}} snippet by default. The default value is FastSpring Checkout.

{{>table-header-color}}

Specifies the hex value of a color (#f5f5f5 by default) that is used in the template of the Default Order Receipt notification and the {{>footer}} snippet, by default. You can also use this in any color attribute in your template, or in another shared snippet.

{{>text-header}}

Provides a block of text designed to render a professional-looking header for use at the top of the Text portions of your templates.

{{>text-footer}}

Provides a block of text designed to render a professional-looking footer for use at the bottom of the Text portions of your templates.

Shared snippets are designed to be customized by you. You can use the Edit command below any snippet to modify the contents (or even the name) of that snippet. The Delete command permanently deletes a snippet. (Please be sure you have identified all templates and other shared snippets that use the snippet you want to delete before deleting it).

 

To Create a New Shared Snippet

  1. From the FastSpring App, select the Settings menu and then click the Customer Emails tab.


     
  2. Click the Shared Snippets option on the left-hand side of the page.


     
  3. Click the  button at the top right-hand corner of the page. The Shared Snippets popup window appears.


     
  4. In the Snippet Tag field, enter the name you want to use to reference this snippet elsewhere (i.e., in notification templates and other snippets). You do not need to enter the curly brackets {{}} or the > symbol; just enter a name with only letters, numbers, and dashes (no punctuation). The curly brackets and the > symbol are automatically added to the name you have entered when you save the snippet.
  5. In the Snippet Text/HTML Value field, enter or paste in the contents of the snippet. That is, enter the value that will replace the Snippet Tag entered above when notification templates or other snippets are processed. In the example below, we are creating a snippet that inserts a new paragraph containing a link to our blog, with a custom translation as a call to action.


     
  6. Click Add to save and finish adding the new snippet. A new card for the new snippet appears on the list of shared snippets.


     

back to list

 

Translations

Translations work similarly to shared snippets in that you can enter a placeholder variable in your notification's template that will automatically be replaced by another value defined elsewhere when FastSpring sends the email messages. In this case, there is a particular set of snippets defined on the Translations page of the Customer Emails tab. The customer's language used for the order is automatically evaluated, and the corresponding translation is automatically rendered. For example, suppose you include {{translate "Total"}} in the body of your notification. If a customer processes an order with Spanish selected, the value for the Total= entry found on the Spanish page of the translations will automatically be rendered in the email message.

 Note

The Default Order Receipt notification and some of the shared snippets that are available by default use a variety of translations for which FastSpring has supplied the translated text. If you create any additional translations, be sure to enter the actual translated text in each language as needed.

 

To Enter Translated Text for Existing Translation Words and Phrases

  1. From the FastSpring App, select the Settings menu and then click the Customer Emails tab.


     
  2. Click the Translations option on the left-hand side of the page.

     Note

    The red exclamation mark next to the Translations option indicates that there are phrases awaiting translation text in one or more languages.
     
  3. On the left-hand side of the Translations page, select the language for which you want to enter translations. Then, simply click in the text area and begin entering translations for each word or phrase following the equals sign (=).

  4. After entering translations for the words and phrases in each supported language, click .

 

Adding New Words or Phrases for Translation

When you are ready to add new words or phrases to be translated, there is no need to go through any special process of adding items to the list of translations. Instead, simply enter {{translate and then type the word or phrase you want to translate between double quotation marks (") and followed by two closing curly brackets (}}).

For example, suppose you want to set up translations for the phrase "Be sure to check out our blog at." To do this, enter the following inside the notification template or the shared snippet where this phrase is to appear:

{{translate "Be sure to check out our blog at"}}

This syntax tells the notification system to look for translations on the Translations page. As soon as you save the notification template or shared snippet you are working on, the new translation will appear in the list on the Translations page. That is all you have to do to add new words or phrases to the list. When you are ready, you can return to the Translations page and enter translations for the new phrase in each supported language.

The following brief video illustrates the process of creating a new translation for use in a shared snippet. Notice that at the beginning of the video, there are a total of eight phrases that need translations for the Spanish language. After creating the shared snippet with a new translation phrase, nine phrases need translations in Spanish. We then enter the translated text for the new phrase in Spanish and save our work.

You can edit any translation by merely selecting the language on the left, clicking in the text area, and making your changes. You can even delete translations via this method as well. (Please be sure you know all of the shared snippets or places in a notification that use the translation before deleting it).

back to list

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.