---
title: "Document templates: what, why & how."
description: "This article offers a guide to document templates: what they are, and how to set them up and use them."
url: https://help.qargo.com/us/articles/246339-document-templates-what-why-how
locale: us
updated: 2026-08-21
---

# Document templates: what, why & how.

## Summary {#h_8bf77434b0}

-   **_What is a Qargo template?_**

    -   A customizable, reusable blueprint for generating business documents such as invoices, delivery receipts, loading sheets, quotes, etc.
    -   Can be used in tasks to automatically generate and/or send documentation.
-   **_Why use templates?_**

    -   Templates allow users to define how documents look and what data is included.
    -   Each company can generate documents in a preferred format, tailored to the company's workflow, language and branding.
    -   All required data is filled in dynamically from the TMS.
-   **_How are templates used?_**

    -   Used to create documents associated with orders and loads.
    -   Paired with workflow tasks, documents can be generated seamlessly, at the appropriate time.
    -   Automatic generation reduces data entry errors and, paired with contact tasks, makes workflows more efficient, i.e., sending a POD or invoice by email, etc.

**Example:** **_'Generate document'_** tasks

![](https://help.qargo.com/media/d7eb5cf0d4f9-image.png)

-   **3 core components:**

    -   _Handlebars template:_ dynamic placeholders to insert data
    -   _Template schema:_ structured definition of all dynamic fields available in the template; can include lists, tables, text, etc.
    -   _Data model:_ actual data passed to the template when it is generated (i.e., order value)
-   Fields in the template schema define which dynamic data elements can be pulled in and shown, or repeated.

    -   Fields can be simple, i.e., 'title', or more complex ones for lists and tables that require parameters.
-   Templates can be configured by editing schemas and visual layouts.

    -   Select which fields to show and define logic (i.e., if/else, conditions, etc.)
-   Document generation: the template pulls the latest data and fills out the dynamic fields according to the template schema and data model.

    -   The output is a ready-to-use document in the desired format (i.e., PDF, CSV)
-   Templates can be global or tenant-specific.

    -   Global template = base layout that can be overwritten, or extended with custom variables
    -   Tenant template = tailored for special requirements, i.e., meeting legal or regulatory needs.
-   Supported features in templates:

    -   Multi-language support (localization), where enabled
    -   Tables and context-specific loops
    -   Custom helpers (such as formatting dates, barcodes, etc.)
    -   Handling of special cases and conditionals, i.e., if a field is empty, do not show it
    -   Attachments or images, i.e., signatures
-   Handlebars expressions allow for advanced logic.

![](https://help.qargo.com/media/da46670d86d2-image.png)

* * *

## Terminology {#h_575846571e}

| **Term** | **Definition** |
| --- | --- |
| **Qargo template:** | Standard, global template versions provided and maintained by Qargo. They act as a reference library and are easy to adapt as needed for branding, language, special data requirements, etc. |
| **Tenant template** | Customized template specific to the tenant (account) |
| **External template** | Document templates from an outside source that can be used or referenced. These can include templates shared across multiple organizations or locations, industry-standard formats and templates imported from external systems, i.e., credit memos, self-bills, load sheets, CMRs. |
| **Base template** | Generic template used to create a new document template. It is selected from a drop-down of predetermined options, based on the category of document being created, i.e., 'invoice'. |
| **Archived template** | Templates that are no longer supported in the platform, typically replaced with an updated version. |
| **Handlebars expression** | Handlebars expressions are special placeholders and logic blocks used in templates to insert data and add conditional or repeating logic when generating documents or emails. |
| **Context tag (blue)** | Shown next to particular fields or rows in the template editor. It indicates that a field is tied to a specific part of the underlying data, i.e., stops, which then show as one row per stop. |

![](https://help.qargo.com/media/09784e228563-image.png)

![](https://help.qargo.com/media/c0e762505678-image.png)

* * *

## Understanding template layout {#h_5436d95364}

When adding a new template, a base template must be selected first. Once it is selected, the data rows and the preview panel (#3 Visualize) are shown. The template shows with generic data.

![](https://help.qargo.com/media/963f989321d9-image.png)

1.  On the **New template** page, select the appropriate **Base template** from the drop-down list.
2.  **Configure** the new template. Give the new template a name that makes the use case easy to identify. Modify any fields to customize the template, or use the base template as is.
3.  **Visualize** the template format in the preview panel. Clicking an element in the preview panel highlights the corresponding data row. Click into the row if the displayed data needs to change.

::video{src="/media/video/34bcde4b39bd-2025-06-20_12-45-45-1-.mp4"}

-   Edit the template data by clicking into the appropriate row and editing the content.

    -   Clicking into the row or using the 'eye' icon highlights the data set from this row in the preview panel.
    -   Clicking information in the preview panel highlights the row where that data set can be edited.
    -   Use the **Data owner** field to view live data. The options displayed relate specifically to the document. In the example below, for instance, the document is a billing proposal, so the options shown in the data owner field are carrier invoices.

::video{src="/media/video/4f38b0dc3c27-2025-06-20_15-21-09-1-.mp4"}

* * *

## Understanding edit icons {#h_aa3898f3c5}

-   Clicking into a row to edit details displays a selection of edit options.

![](https://help.qargo.com/media/81731f89eab0-image.png)

1.  Text editing options, including bold, italic and underline; font size and color. H and h format the data as Heading 1 (H) or Heading 2 (h).
2.  Add a URL link to a website. A pop-up window displays where the link can be added.
3.  Add data as bullet points or a numbered list.
4.  Syntax blocks for creating more advanced conditions using expressions that combine multiple variables or conditions.
5.  Formatting options to add a page break or HTML block

### Using syntax blocks  {#h_5ef90025ec}

![](https://help.qargo.com/media/f6ec65742470-image.png)

-   When editing a template, syntax options can be used to make templates reflect specific conditions.

![](https://help.qargo.com/media/caf25e5a326a-image.png) **Handlebars expressions**

-   **_Handlebars expressions_** are used to select **variables** associated with the document. The variables displayed in the drop-down are specific to the document and the associated row.

    ![](https://help.qargo.com/media/5c29b33d2e38-image.png)


![](https://help.qargo.com/media/20bc909793cf-image.png) **'If' block**

-   Use the **IF** block in a document template to display certain content or formatting only under specific conditions, based on the data. For example, a field can be shown only if it is not empty, or a row can be highlighted only if a value exceeds a threshold.⁠⁠​
-   **Common scenarios:**

    -   Hide charges with amount 0: use an IF block to display a charge only if its value is more than zero.
    -   Show content conditionally: for example, display a note or section only if a field contains certain text (such as a specific contract carrier name or a filled-in comment).
    -   Conditional formatting: make text bold or apply special styles when a value meets a condition (e.g., bold a location if a related note exists).⁠⁠​

    ![](https://help.qargo.com/media/6ae9979e73f3-image.png)


:::callout{tone="info"}
📚 IF blocks can be combined with ELSE for more complex logic.
:::

![](https://help.qargo.com/media/f8d63d1309c3-image.png) **For block**

-   The **FOR** block is a powerful feature in the Qargo document template editor that enables dynamic, data-driven document generation.
-   To list all products for an order, with each product and its description on a new line, add a FOR block for the goods array and place the product details inside the block. The FOR block ensures each product gets its own line in the final document⁠⁠.

    ![](https://help.qargo.com/media/b4385abb177d-image.png)


![](https://help.qargo.com/media/3122906af688-image.png)**Combine statement**

-   Use the **COMBINE** block to display a joined or aggregated list from an array in the template, such as joining a list of values into a comma-separated string.
-   Unlike a FOR block, which iterates over each item and renders content repeatedly, the Combine block processes the array to output a single result, typically by concatenating or otherwise aggregating its elements.
-   One important limitation is that IF statements (conditional logic) cannot be used inside a Combine block. This means the Combine block is best suited for straightforward aggregation without item-level conditions.

    ![](https://help.qargo.com/media/eb18f78683f8-image.png)


* * *

:::callout{tone="info"}
📚 Specific documents cannot be duplicated. To copy an existing template, for instance a customer-specific invoice template, contact Qargo Support.
:::

## Add new template {#h_a554b7a8de}

-   Navigate to **Configuration > Templates**
-   Click **Add template**
-   Select the document type from the drop-down list.

    -   **Note**: additional options may be available, i.e., "Invoice" gives an option for invoice or credit memo, and "Loading sheet" gives an option for load or resource

::video{src="/media/video/6c54a27f6b6d-2025-06-30_13-57-15-1-.mp4"}

-   Select a base template from the drop-down.

    ![](https://help.qargo.com/media/05abd201da3a-image.png)


-   In the **Visualize** panel, clicking the **Data owner** field displays matching records for this type of document. Selecting one of them updates the template preview to show customer data.

    ::video{src="/media/video/f466209ed045-2025-06-30_14-07-03-1-.mp4"}

    -   If the basic template provides all the data in the required layout, give the template a name and click **Save**.
-   If the template layout needs modifications, use the rows in **Configure** to update the data.

### Modify a template {#h_c32012d005}

:::callout{tone="info"}
📚 To modify an existing template, use the **Visualization tool** to identify the fields that need to be updated. For instance, if a reference number on an invoice needs to be updated, the steps below update it.

-   Open the template (i.e., invoice)
-   In the preview panel, click the data element that needs an update
-   The relevant configuration field is highlighted on the left side
-   Open the drop-down to expose the data
-   Update the data in the configuration field and verify in the preview that the update displays as expected
-   Click **Save**
:::

-   The template format is available in either HTML or PDF.
-   With PDF, additional formatting is available. Expand the **PDF configuration** row.

    -   Changes made in the configuration panel are previewed in the right panel.

    ![](https://help.qargo.com/media/9375fb4afa1f-image.png)

-   To modify individual elements, click the element to highlight the row that needs the update.

    -   Click into the row and the edit options display.
    -   Select the appropriate action from the options.
    -   Once it is selected, the modified data updates in the preview/visualize window for confirmation.
-   Use the **Background** option to upload an existing letterhead to use as the background layout for an invoice.

    ![](https://help.qargo.com/media/5e7c17fc33a3-image.png)

-   Once the template matches the required layout and content, click **Save**.

::video{src="/media/video/dfe1379400f1-2025-06-30_15-58-25-1-.mp4"}

:::callout{tone="info"}
📚 If a customer-specific template needs to be duplicated, contact Qargo Support to request the update.
:::

* * *

### Configuring the row sort order {#h_6963ba72da}

The document template editor now allows lines to be sorted by a chosen field. Every PDF made from that template follows that order: sales invoices, credit memos, contract carrier self-bills, billing proposals and load exports. The setting is defined once on the template and applies every time.

Until now, lines always came out in the same fixed order (by the planned start time of the first stop, then by charge name) with no way to change it. That order is now configurable.

### Setting a sort key {#h_59b4663596}

1.  Navigate to **Configuration > Templates** and open the template to edit, or add a new one.
2.  Select the row-iteration block that emits the order or charge rows.
3.  In the **Sort** section, set **Sort by** to the field the document should follow, then choose a **Direction** of **Ascending** or **Descending**.
4.  Add a secondary **Sort by** as an optional tiebreaker, for example driver name first and estimated start timestamp second.
5.  Save the template. Every PDF generated from that template then respects the configured sort.

![](https://help.qargo.com/media/be5296e1baeb-image.png)

### Available sort keys {#h_87c269fddf}

The keys offered depend on the type of rows the selected block renders.\
For order rows (sales invoice and credit memo templates):

-   **Order number**
-   **Customer reference**
-   **Delivery date (requested)**
-   **Delivery date (actual)**
-   **Pickup date (requested)**
-   **Pickup date (actual)**
-   **Last shipment stop timestamp** (the existing default)

For charge rows (carrier invoice and billing proposal or self-bill templates):

-   **Driver name**
-   **Resource (vehicle) name**
-   **Load number**
-   **Estimated start timestamp** (the existing default)
-   **Charge name**

Load export templates also expose **Vehicle** and **Driver** as sort keys.

### Common uses {#h_fe2b5a9a42}

-   A sales invoice sorted by **Customer reference** or **Delivery date** so the customer can reconcile it against their own records.
-   A contract carrier self-bill or billing proposal grouped by **Driver name** (primary) and then chronologically by **Estimated start timestamp** (secondary), so each driver's loads sit together.
-   A load export grouped per vehicle by using **Resource (vehicle) name** as the sort key.

:::callout{tone="note"}
The default sort matches the previous behavior, so existing templates are not affected until a new sort key is chosen. There is no automatic migration.
:::

:::callout{tone="info"}
📚 The sort applied on the **Invoices**, **Credit memos**, or **Loads to bill** list views is independent of the template. The order of rows inside a generated PDF is driven only by the sort configured on the template.
:::

:::callout{tone="note"}
In this release the configurable sort controls the order of order rows or shipment rows. Charge lines nested within a shipment block keep their existing order, and manual drag-and-drop row ordering and the order of documents in a merged multi-document PDF are not covered. For blocks with a subtotal per driver, vehicle, order or load, see [Grouping lines and subtotals](#h_0233169384).
:::

* * *

## Grouping lines and subtotals {#h_0233169384}

Invoice templates can print charge lines in blocks, with a subtotal under each block. This helps customers and contract carriers who need a total per truck, per driver, per order or per load, without working it out by hand. The grand total always stays at the bottom of the document.

Two options are available:

-   Two grouped-lines base templates that group lines by a chosen key.
-   An optional subtotal row after each order or load on the existing invoice templates.

### Grouping lines by order, load, vehicle or driver {#h_fdd064632a}

:::callout{tone="info"}
🧰 Setting up a template needs a Super Admin. Contact Qargo Support or the onboarding team for help with a customer-specific template.
:::

1.  **Navigate** to **Configuration > Templates** and click **Add Template**.

    ![The Templates page with the Add Template button](https://help.qargo.com/media/90db2ec05846-templates-add-template.png)

2.  **Select** the document type, then pick the base template: **Invoice template - grouped lines** for sales invoices and credit memos, or **Purchase invoice template - grouped lines** for billing proposals and self-bills.

    ![Choosing the document type](https://help.qargo.com/media/e6d6256bfbb3-templates-document-type.png)

    ![The base template list with Invoice template - grouped lines](https://help.qargo.com/media/cdbf3045f255-templates-base-grouped-lines.png)

3.  **Expand** **Template options** and open **Line grouping settings**.
4.  **Set** **Group lines by** to the key the document should follow.

    ![The Group lines by field in Line grouping settings](https://help.qargo.com/media/c5e07e56d1ee-templates-group-lines-by.png)

5.  **Save** the template. Every document generated from it prints one block per group.

    ![Preview of a sales invoice grouped by order, with a subtotal under each order](https://help.qargo.com/media/0e5a49719885-templates-grouped-preview.png)

The keys on offer depend on the document:

-   Sales invoices and credit memos: **Order**, **Vehicle** and **Driver**.
-   Billing proposals and self-bills: **Load**, **Order** (the cost order of the line), **Vehicle** and **Driver**.

![The Group lines by options on a purchase invoice template: Driver, Order, Load and Vehicle](https://help.qargo.com/media/35193e9056f2-templates-group-keys-purchase.png)

Each block has a header (for example the order number, the license plate or the driver name), its charge lines and a subtotal. Subtotals print by default. To hide them, empty the **group_subtotal_label** field on the template. Group headers and lines stay in place.

![The group_subtotal_label field and the subtotal row in the preview](https://help.qargo.com/media/2c1ad77a6b83-templates-group-subtotal-label.png)

Lines with no value for the chosen key are collected in one block at the end of the document, with its own subtotal. The block is named after the key: "No vehicle assigned" or "No driver assigned".

:::callout{tone="note"}
📚 Charges added directly to an invoice without an order print in their own block after the groups. They are left out of every group subtotal and still count in the grand total. A subtotal always covers a whole group: a subtotal over a hand-picked set of charges is not possible.

![A sales invoice grouped by driver, with a charge without an order printed after the groups](https://help.qargo.com/media/aa096cb75773-templates-charge-without-order.png)
:::

:::callout{tone="info"}
🧰 Good to know:

-   Grouping needs a template built on one of the two grouped-lines base templates. An existing template cannot be switched to grouping.
-   Only one grouping key applies per template. A document cannot be grouped by vehicle and then by order.
-   There is no grouping by product. For a total per charge, use the base template **Total invoice template - charges grouped by name**.
:::

How lines are assigned to a vehicle or driver:

-   On sales documents an order is never split over two groups. All its charge lines print under the vehicle or driver of the delivery stop.
-   Vehicle means the primary tractor, rigid or van. A trailer is never used as a group.
-   A load with two primary tractors shows both plates in one header. The same goes for two primary drivers.

:::callout{tone="info"}
📚 The order of the blocks follows the sort settings of the template (see [Configuring the row sort order](#h_6963ba72da)). Sort by **Driver name** first and by date second to list each driver's loads in chronological order.
:::

### Adding a subtotal row on existing invoice templates {#h_f208069a26}

The existing sales invoice templates (1, 2 and 3 columns, total with details, and total with grouped charges and details) and the matching purchase invoice templates can print a subtotal row after each order (sales) or each load (purchase).

1.  **Navigate** to **Configuration > Templates** and open the template to change.
2.  **Fill in** **order_subtotal_label** on sales templates, or **shipment_subtotal_label** on purchase templates, for example with "Subtotal".

    ![The order_subtotal_label field on a sales invoice template](https://help.qargo.com/media/1bd4eb75b78f-templates-order-subtotal-label.png)

3.  **Check** the preview in the **Visualize** panel. The row appears under the last charge line of every order or load, in the same column layout as the charge rows.
4.  **Save** the template.

Both fields are empty by default, so existing documents do not change until a label is entered. To remove the row again, empty the field completely.

:::callout{tone="note"}
📚 A template that already prints a load subtotal above the charge lines through its own configuration shows two subtotals per load once a label is entered. Clear the older setting first.
:::

### Good to know {#h_6b1e0c4d92}

-   There is no page total and no setting for rows per page. A multi-page invoice shows its total on the last page only.
-   There is no summary block that lists every group's total before the detail lines.

* * *

## Practical troubleshooting: examples for invoice templates {#h_df85dd75fd}

-   **Background not displaying**: verify that the file format matches the supported types and make sure the **Show in PDF** option is enabled during editing.
-   **Error** `Preview could not be rendered or updated. Please verify that all open '#{{' tags have a corresponding '}}' tag.`: the preview rendering may fail because of the large size of the document. Test with a smaller document (only a few orders) to check whether the preview works. Document generation is not affected by this.
-   **Element removal challenges**: if unwanted elements such as an email address are part of a background file, edit that file externally with a tool such as a PDF editor before re-uploading it in the template's configuration settings.
-   **Recurring background issues**: always save edits to the background file before re-uploading it, and verify the updates with the preview function.
-   **Wrong reference numbers:** to update the reference number that appears on invoices:

    1.  Navigate to the **Templates** section in Qargo.
    2.  Open the template used for the specific customer's invoices.
    3.  Click into the address field. This highlights the field in the left panel where the reference is stored.
    4.  Update the reference number to the desired value.
    5.  Save the template. The updated reference applies to all newly created invoices. If an invoice already has the status **Invoiced**, the PDF can be updated by re-triggering the invoice PDF so the new reference appears.
-   **Verifying customer references in Peppol XML**: to confirm that a customer reference is present in the Peppol XML for an invoice:

    1.  Open the invoice in Qargo.
    2.  Open the Peppol XML preview.
    3.  Use the search function to locate the reference value by pasting the expected reference number.
    4.  Verify that the reference appears in the XML in the right-hand preview pane.


## Related articles

- [Video - How to group lines and subtotals on sales and purchase invoices?](https://help.qargo.com/us/articles/894190-video-how-to-group-lines-and-subtotals-on-sales-and-purchase-invoices.md)
- [Custom exports: using the Expression Builder](https://help.qargo.com/us/articles/467741-custom-exports-using-the-expression-builder.md)
- [Templates: setting up groupage CMRs](https://help.qargo.com/us/articles/425074-templates-setting-up-groupage-cmrs.md)
- [Invoices – Create a contract carrier self-bill from loads](https://help.qargo.com/us/articles/133825-invoices-create-a-contract-carrier-self-bill-from-loads.md)
- [Orders: orders list view functions](https://help.qargo.com/us/articles/133839-orders-orders-list-view-functions.md)
