# Templates URL: https://docs.sparklayer.io/developers/templates Build custom SparkLayer invoice, quote and email templates in Liquid, using the currency, translate, ldate and country filters, sections and language files. Templates set the design and wording of the PDFs and emails SparkLayer creates, such as invoices, quotes and purchase approval emails. They're written in [Liquid](https://shopify.github.io/liquid/), and each one receives the data listed under [Available data](#available-data). ## The templates | Template | Type | What it's for | | --- | --- | --- | | invoice.liquid | PDF | The invoice | | quote.liquid | PDF | The quote | | limited-user-purchase-review\.liquid | Email | Sent when a [limited user](https://docs.sparklayer.io/help/glossary.md#limited-user) places a purchase that needs approving | | limited-user-purchase-approve.liquid | Email | Sent when a limited user's purchase is approved | | new-quote-notification-to-merchant.liquid | Email | Tells you a customer has asked for a quote | | quote-assigned-notification-to-agent.liquid | Email | Tells a sales agent a quote has been assigned to them | | purchase-history-message-notification-to-agent.liquid | Email | Tells a sales agent about a new message on an order or quote | | purchase-history-message-notification-to-customer.liquid | Email | Tells a customer about a new message on an order or quote | | email-header.liquid | Section | The header every email shares | | email-footer.liquid | Section | The footer every email shares | Only the templates above can be used. Any other files uploaded to a theme are discarded, including supporting files such as images and fonts. ### Create and upload a template 1. In the SparkLayer Dashboard, go to **Settings > Templates** in the SparkLayer Dashboard ([open](https://app.sparklayer.io/configuration/theme)), or **SparkLayer Wholesale > Settings > Templates** in the Shopify app. 2. Click **Create template**. SparkLayer creates a template theme for you to edit. 3. Add only the files you'll change, and edit them in the SparkLayer editor. Click **Save** to create a revision. To go back, open a previous revision from the **Revisions** drop-down and save it. 4. For bigger changes, download the template as a ZIP file, work on it with your own tools, then zip it up and upload it. A new template is empty, so it falls back to SparkLayer's core templates and language files until you add files to it. Once you add a file, it's no longer updated from the core templates: if a new feature changes a core template, copy the change into your file. See [Templates](https://docs.sparklayer.io/help/dashboard/settings.md#templates) in the Help Center for more. ### Template markup and Liquid Templates are written in [Liquid](https://shopify.github.io/liquid/) and have access to most Liquid tags and filters, plus the helper filters below. Add styling in the template, in a `style` element or inline styles. All styles are inlined when the template is rendered, for better compatibility with email clients. The email templates are tested in modern web-based email clients such as Gmail. Older email clients, such as desktop versions of Outlook, aren't supported. Test your custom email templates, because email clients often handle modern HTML and CSS badly. ### Filters and blocks - [Currency](#currency) - [Translate](#translate) - [Localised date format](#localised-date-format) - [Country from country code](#country-from-country-code) - [Template sections](#template-sections) ### Currency Use the `currency` filter for monetary values. It renders the currency with the right formatting for the locale. ```liquid title="Template" {{ "9.99" | currency: "gbp" }} ``` ```text title="Output" £9.99 ``` To change the currency formatting, pass one of these options: - `display_none` - `display_code` - `display_symbol` (default) ```liquid title="Template" {{ "9.99" | currency: "gbp", "display_code" }} ``` ```text title="Output" GBP 9.99 ``` The filter also has a shorthand alias, `c`, which works the same way. ### Translate Use the `translate` filter to translate text in a template. The theme needs a language file with the translation strings. See [Internationalisation and translations](#internationalisation-and-translations) for how to add language files. ```json title="en.json" { "example": { "heading": "Welcome to SparkLayer!" } } ``` ```liquid title="Template" {{ "example.heading" | translate }} ``` ```text title="Output" Welcome to SparkLayer! ``` The filter also has a shorthand alias, `t`, which works the same way. To insert values into a string, add numbered slots to the string and pass the values as arguments to the filter: ```json title="en.json" { "example": { "heading": "Dear ${1} of ${2}" } } ``` ```liquid title="Template" {{ "example.heading" | translate: "Jeremy Sparks", "SparkLayer" }} ``` ```text title="Output" Dear Jeremy Sparks of SparkLayer ``` This filter translates using the store locale from the merchant data (`data.merchant`), falling back on the `en` translation file if no translation is found for the respective locale. ### Localised date format Use the `ldate` filter to format dates for a locale. By default, it uses the store's locale from the merchant data (`data.merchant`). To use another locale, pass it as a parameter. ```liquid title="Template" {{ "2024-10-22T16:18:02.196Z" | ldate }} ``` ```text title="Output" 22/10/2024 ``` With a locale: ```liquid title="Template" {{ "2024-10-22T16:18:02.196Z" | ldate: "fr-CA" }} ``` ```text title="Output" 2024-10-22 ``` ### Country from country code Use the `country` filter to show a country name from its country code. This helps with address data, which stores the country code rather than the name. ```liquid title="Template" {{ "gb" | country }} ``` ```text title="Output" United Kingdom ``` Country names are always returned in English, whatever the store's locale. ### Template sections Use the `section` tag to include a section template. Only the section templates listed under [The templates](#the-templates) are supported; you can't add custom sections. ```liquid title="Template"
{% section email-header %}

Content

{% section email-footer %}
``` ```html title="Output"

Hello World

Content

``` ## Internationalisation and translations You can add language JSON files to a theme to translate its templates. Name each file with a language code (such as `en` or `fr`) that matches the locale used by your store. The translations in these files are available through the [translate](#translate) Liquid filter. By default, the filter uses the store's locale. If your language files have no translation for a key, it falls back to SparkLayer's core language files, with `en` as the final fallback. ## Available data Templates get their data through the `data` Liquid variable, for example `data.merchant.store_name`. | Template | Top-level objects | | --- | --- | | invoice.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [settings](https://docs.sparklayer.io/developers/templates/template-objects.md#invoicesettings) | | quote.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) | | limited-user-purchase-review\.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) | | limited-user-purchase-approve.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) | | new-quote-notification-to-merchant.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase) | | quote-assigned-notification-to-agent.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [assignment\_details](https://docs.sparklayer.io/developers/templates/template-objects.md#assignmentdetails) | | purchase-history-message-notification-to-agent.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [purchase\_history\_message](https://docs.sparklayer.io/developers/templates/template-objects.md#purchasehistorymessage) | | purchase-history-message-notification-to-customer.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant), [purchase](https://docs.sparklayer.io/developers/templates/template-objects.md#purchase), [purchase\_history\_message](https://docs.sparklayer.io/developers/templates/template-objects.md#purchasehistorymessage) | | email-header.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) | | email-footer.liquid | [merchant](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) | The data varies by template, but every template has the store details (`data.merchant`). [This object](https://docs.sparklayer.io/developers/templates/template-objects.md#merchant) holds the store's general information, which you can change in the [SparkLayer Dashboard settings](https://docs.sparklayer.io/help/dashboard/settings.md). ## Next steps - [Template objects](https://docs.sparklayer.io/developers/templates/template-objects.md): every object and property available to templates. - [Templates in the Help Center](https://docs.sparklayer.io/help/dashboard/settings.md#templates): what merchants can change with templates. - [Languages and international](https://docs.sparklayer.io/help/storefront/languages-and-international.md): the languages SparkLayer supports.