> ## Documentation Index
> Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Document templates

## 1. Concepts

### Documents versus emails

**Communications > Document Templates** is where you design the actual billing and legal documents Zenskar generates, separate from the emails that deliver them. Where [Email Templates](/docs/20240301/product-modules/more/communications/email-templates) controls the subject line and body of a message, Document Templates controls the layout of the document that gets attached to it, for example the invoice PDF itself.

Document Templates supports a narrower set of types than Email Templates, since some email types (Payment Reminder, Usage Report, Custom Email) never carry a document attachment:

* **Invoice**
* **Payment Receipt**
* **Refund Receipt**
* **Contract**
* **Credit Note**

As with email templates, several document templates of the same type can exist, but only one can be the **default** for that type at a time. An email template's attach-document toggle always resolves to whichever document template is marked default for the mapped type, so setting the right default here is what determines what customers receive.

### Editing a document's HTML

Document templates are built from raw HTML with Mustache templating placeholders, such as `{{customer.name}}` or `{{invoice_data.total}}`, that Zenskar fills in when the document is rendered. See the [Templating guide](/docs/20240301/product-modules/more/communications/templating-guide) for how Mustache syntax works and which variables are available. There is currently no visual or WYSIWYG document editor. How the HTML is edited depends on whether the template is new or already exists:

* **A brand-new template** opens into a completely empty code editor. There is no starter or boilerplate HTML, no option to duplicate an existing template, and no placeholder validation while creating it, so a typo in a placeholder name only surfaces later, once the template is saved and reopened through Edit HTML.
* **An existing template** keeps its HTML behind two explicit actions instead of showing it inline:
  * **Preview** renders the template against sample data, showing roughly what a real document will look like without touching the HTML.
  * **Edit HTML** opens the same code editor used for new templates, with inline validation that flags errors in the markup or in placeholder usage. Validation errors block saving until they are fixed.

### Starting a new template's HTML

Because a brand-new template starts empty, write its HTML using the variable reference pages linked from the [Templating guide](/docs/20240301/product-modules/more/communications/templating-guide) rather than starting from copied HTML. In particular, avoid these two shortcuts:

* **Copying a template's Preview output.** Preview shows the template's placeholders already resolved against sample data, so its HTML contains literal, resolved values, for example a specific customer's name or address, rather than the live `{{placeholders}}` Zenskar needs to fill in per customer.
* **Copying HTML from a different Zenskar organization or environment**, such as a sandbox or test account. If that organization's template was itself built by hardcoding values instead of using placeholders, or if its placeholders resolve to that organization's own branding and sample data, copying it carries that branding and data into the new template.

If a template of the same type already exists in the same organization, opening it and clicking **Edit HTML** is a safe way to see working markup that already uses Zenskar's placeholders correctly, and can be used as a starting point for a new template of the same type.

### Template information

Every document template also has a **Template Information** section with a **Name** and an **Additional Options** free-text field, used for any extra Zenskar-compatible key-value data that should be available when the document renders.

### No version history

<Note>
  Document templates do not keep a version history. Editing a template's HTML overwrites its previous content with no way to roll back. **Set As Default** is the only override mechanism, useful for staging a new layout as a separate template and only pointing production traffic at it once the new layout is confirmed correct.
</Note>

***

## 2. How-to guides

### Create a document template

1. Go to **Communications > Document Templates**, and click **+ Add New Document Template**.
2. On the **Select Document Template Type** picker, choose Invoice, Payment Receipt, Refund Receipt, Contract, or Credit Note.
3. Enter a **Name**, and optionally fill in **Additional Options**.
4. Write the HTML in the code editor, using the variable reference pages linked from the [Templating guide](/docs/20240301/product-modules/more/communications/templating-guide). See [Starting a new template's HTML](#starting-a-new-templates-html) above for what to avoid if starting from copied HTML.
5. Click **Save**.

### Preview an existing document template

Open the template, and click **Preview**. Zenskar renders the saved HTML against sample data, showing the result without entering edit mode.

### Edit an existing document template's HTML

Open the template, and click **Edit HTML**. Make the necessary changes in the code editor. Fix any inline validation errors shown, since saving is blocked until the HTML is valid.

### Mark a template as the default for its type

Open the row's kebab menu, and click **Set As Default**. This is the only override mechanism for document templates; there is no separate publish or versioning step.

### Troubleshooting

* **Save is blocked with a validation error**: the code editor flags problems inline, for example malformed HTML or a placeholder that is not recognized. This validation only runs through **Edit HTML** on an already-saved template, not while first creating one; fix the highlighted issue, and save again.
* **A document shows the wrong branding or a stranger's data instead of the current customer's**: this usually means the template's HTML was copied from a template's Preview output, or from a different Zenskar organization or environment, rather than written with live placeholders. Rebuild the affected section using the variable reference pages linked from the [Templating guide](/docs/20240301/product-modules/more/communications/templating-guide) so the values are filled in per customer.
* **An email's document attachment fails with "no default document template"**: no document template of the required type has been marked default yet. Create one here, and use **Set As Default**, then retry the email template's attachment toggle. See [Email templates](/docs/20240301/product-modules/more/communications/email-templates).
* **There is no way to revert an HTML change**: document templates do not keep a version history. Keep a copy of prior HTML outside Zenskar to be able to roll back a change.

***

## 3. Reference

### Location

**Communications > Document Templates**.

### Document types

| Type            |
| --------------- |
| Invoice         |
| Payment Receipt |
| Refund Receipt  |
| Contract        |
| Credit Note     |

### Fields

| Field              | Required | Notes                                                                                                               |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| Name               | Yes      |                                                                                                                     |
| Type               | Yes      | Chosen once, at creation                                                                                            |
| Additional Options | No       | Free-text, Zenskar-compatible key-value data                                                                        |
| Template HTML      | Yes      | Raw HTML with templating placeholders; new templates edit inline, existing templates go through Preview / Edit HTML |

### List columns

| Column          | Description                      |
| --------------- | -------------------------------- |
| Name            | Template name                    |
| Type            | Document type                    |
| Last Updated At | When the template was last saved |
| Created At      | When the template was created    |

### What is not currently supported

| Capability                                                                | Status                                                                                         |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Visual or WYSIWYG document editing                                        | Not available. All editing is raw HTML                                                         |
| Starter HTML, duplicating an existing template, or resetting to a default | Not available. A brand-new template's code editor opens completely empty                       |
| Placeholder validation while creating a new template                      | Not available. Inline validation only runs through Edit HTML, once the template already exists |
| Version history / rollback                                                | Not available. Set As Default is the only override mechanism                                   |