> For the complete documentation index, see [llms.txt](https://learn.withessential.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.withessential.com/administration/settings/edit-a-document-templates-design-with-edit-code.md). # Edit a document template's design Change the wording on your invoice or quote document right on the document itself. **Edit template** opens a full-screen editor showing the real document rendered with sample data: click any text and type to change it. For layout, styling, and logic changes, switch to **Edit code** and edit the template's Liquid source with a live preview beside it. > **Where to find it:** Settings -> Invoicing, the Invoice tab (or Settings -> Quotes, the Quote tab), in the template section. Select **Edit template** above the preview, or **Customize** on a style card under **Browse styles**. ## Before you start Editing a template needs permission to change that template type **and** the document-template source-editing permission. Without it, you can still browse the template library, switch templates, and preview them, but the **Edit template** and **Customize** buttons won't appear. If you need to edit a template, contact your business's administrator to review your role. ## Open the editor * **Edit template** above the preview opens the template you're working on. * **Customize** on a style card (under **Browse styles**) selects that style and opens it in the editor. * When your template no longer matches a library style, the "This template has been customized" banner also has an **Edit template** button. The editor opens in **Visual**: **Sample data** on the left, the document on the right, and **Insert variable** and **Reset to default** above the document, beside the hint "Click any text to edit it. Use Insert variable to add details like the customer's name." The **Visual / Edit code** switch at the top changes modes. A template with no content yet opens in Edit code, since there's nothing to click. ## Change text in Visual 1. Point at the document: text you can change shows a dashed outline. Click it and type. 2. Variables — values such as the customer name, dates, and totals — show sample values. Pointing at text highlights the variables in it; hover a variable to see its name. Press Backspace or Delete next to a variable to remove it. 3. To add a variable, use **Insert variable** (see [Add a variable](#add-a-variable)). 4. Select **Save template**. A few things to know: * Enter adds a line break. Pasted text arrives as plain text. * What you type is always plain text. Typing `{{` or `{%` doesn't create a variable and can't break the template. * Text inside a repeated section, such as a line-item row, changes in every row. * Bold, italic, layout, styling, and logic (sections that repeat or only show in some cases) are changed in Edit code. **Insert variable** leaves out the start and end markers of repeating sections for the same reason. * Text that only appears in some situations isn't in the sample document, so you can't click it. Try different sample data (below), or change it in Edit code. * Text that doesn't outline when you point at it can't be changed in Visual; change it in Edit code. ## Add a variable A variable fills in a detail, such as the customer's name or the total, when the document or message goes out. **Insert variable** is always available in Visual, and there are two ways to use it: * **Click, then pick:** click in the text where the variable should go, select **Insert variable**, and pick one. It goes in at your cursor. * **Pick, then click:** with no cursor in the text, select **Insert variable** and pick one. A banner reads "Click where "*name*" should go", and the text you can edit is highlighted. Click where the variable should go to place it. To cancel, select **×** on the banner or press Esc. The list opens with a one-line reminder of how it works. When it has more than eight variables, type in **Search variables** to filter it. Once placed, a variable works like any other: hover it to see its name, or press Backspace or Delete next to it to remove it. **Insert variable** works the same way on every template in Settings that has a Visual mode: quote and invoice documents, the receipt and receipt email, the invoice and quote emails, the purchase order template, visit reminders, automated outreach and its confirmation email, calendar event content, and work acknowledgments. Each screen lists the variables its template can use. ## Edit code Select **Edit code** in the switch at the top. The **Source** tab shows the template's raw Liquid source, with a live preview on the right that updates as you type. A panel of available variables sits beside the source; click any variable to insert it at your cursor, so you don't have to remember the exact code. Use Edit code for anything Visual can't do: formatting, layout, styling, adding or removing sections, and conditions or loops. Switching between Visual and Edit code never loses or rewrites anything. Visual changes only the text you edit; the rest of the template, including your code formatting, stays exactly as it was. ## Try different sample data The document renders with sample data so you can see real layout without affecting any customer document. In Visual, use the **Sample data** panel on the left; in Edit code, open the **Sample data** tab. Switch the sample customer, property, and line items to check how the template handles different data. Open **Service property** and type in the search field to find a sample property by name or city. With the picker open, use the arrow keys to move through results and Enter to choose a property; Escape closes the picker. ## Errors and warnings Edits made in Visual can't break a template. Edit code can — for example, an `{% if %}` without its `{% endif %}`. Each template screen in Settings checks the template as you edit and shows a notice near Save (calendar event content shows its errors under the preview instead — see [Customize what synced events say](/administration/settings/connect-a-calendar-google-or-microsoft-outlook.md#customize-what-synced-events-say)): * **Error (red):** the template you edited can't be read or rendered, so it couldn't be sent or turned into a PDF. The notice reads "Fix this template error to save. As written it can't be sent." and names the problem and the line it's on. Save (here, **Save template**) stays unavailable until you fix it. * **Warning (yellow):** the template uses a variable that doesn't exist — usually a typo, such as `customer.nmae`. The notice names the variable; that spot prints nothing. You can still save. If a template saved earlier already has an error and you haven't changed it, the red notice reads "This saved template has an error, so it can't be sent. Fix it in Edit code." It doesn't stop you saving the screen's other settings — for example, pausing an automation or changing reminder timing. Once you edit that template, fix it before you can save. In Visual, a template that can't be rendered shows the error in place of the document; select **Fix in Edit code** to correct it. ## Reset, save, or close **Reset to default** reverts the template to its default: for a library template, that's the library style's default; for a customized template, it's your saved version. It's above the document in Visual and above the source in Edit code. Nothing is applied until you select **Save template**. An **Unsaved changes** marker shows while edits are pending. **Close** returns to the settings page. ## Show item codes on the document Essential's built-in styles don't print item codes, but you can add them in Edit code. Inside the line-item loop, insert the **Item code (when known)** variable from the variable panel — it inserts `{% if item.code %}{{ item.code | escape }}{% endif %}`, so lines without a code print nothing instead of an empty gap. To make it a column, add a header cell alongside the built-in headers (**Parts, Labor, and Items** / Tax / **Qty** / **Unit Price** / **Total**) and put the variable in the matching body cell. The code comes from your pricebook: Essential matches the line's name to your items and uses that item's code. Because a quote or invoice line stores its own copy of the name and price, the code is blank when the line's name doesn't match a pricebook item exactly - a custom line, or a line whose name was edited after it was added - and also when two pricebook items share the same name, since there's no single right code to print. Keep names as they come from the pricebook if you want codes on every line. If a code is missing where you expected one, compare the line's name on the document against the item's name in Settings > Items. The same value is used everywhere the document renders: the preview in the editor, the quote or invoice page, the mobile app, the PDF attached to emails, and the customer's sign or payment page. The sample line items in the preview all carry codes, so you can lay out a code column and see it before you save. ## Related guides * [Choose and customize your invoice document template](/administration/settings/choose-and-customize-your-invoice-document-template.md) * [Choose and customize your quote document template](/administration/settings/choose-and-customize-your-quote-document-template.md) * [Customize your invoice email and receipt templates](/administration/settings/customize-your-invoice-email-and-receipt-templates.md) * [Create Terms & Conditions sets for quotes](/administration/settings/create-terms-and-conditions-sets-for-quotes.md) * [Set up invoice prompt templates for AI drafting](/administration/settings/set-up-invoice-prompt-templates-for-ai-drafting.md) * [Set up quote prompt templates for AI drafting](/administration/settings/set-up-quote-prompt-templates-for-ai-drafting.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://learn.withessential.com/administration/settings/edit-a-document-templates-design-with-edit-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.