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

# Text templates

> Learn how to manage template texts for invoice notes and customer-facing emails.

## Overview

Organizations that create [invoices](/finops/guides/accounts-receivable/invoices/create) or other financial documents may want to use the same memo note or email message text for multiple documents. These texts can be stored in Tesouro as **text templates** and fetched on demand. Templates can include [`{variables}`](/finops/guides/advanced/variables) that serve as placeholders for various customer-specific and document-specific values.

Templates can be created for:

* emails (containing invoices, quotes, credit notes, purchase orders; as well as invoice reminders),
* custom notes included in invoices, quotes, and other documents.

Each organization starts with a predefined set of templates and can also create additional templates.

## List all templates

Each organization starts with a predefined set of templates. To get all available templates, call [`GET /text-templates`](/finops/reference/openapi/text-templates/get-text-templates). You can optionally filter the results by `type`, `document_type`, and `is_default`. (More details on these fields are given below.)

Examples:

* `GET /text-templates?document_type=invoice` - get all templates for Accounts Receivable invoices.
* `GET /text-templates?is_default=true` - get all default templates.
* `GET /text-templates?type=email_header` - get all templates for email subject lines.

## The `TextTemplate` object

Tesouro stores text templates in this format:

```json lines theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "My invoice email subject",
  "document_type": "invoice",
  "type": "email_header",
  "template": "Invoice {invoice_number} from {entity_name}",
  "created_at": "2023-01-20T06:18:28.660Z",
  "updated_at": "2023-01-20T06:18:28.660Z",
  "is_default": false
}
```

The main fields in a `TextTemplate` object are:

* `name` - the display name of a template.
* `document_type` - the document type for which this template was created. Can be:
  * *invoice*
  * *quote*
  * *credit\_note*
  * *discount\_reminder* - [invoice payment reminders](/finops/guides/accounts-receivable/invoices/payment-reminders) sent before the first and second early payment dates (if any) if the invoice is still unpaid.
  * *final\_reminder* - payment reminder sent before the invoice due date.
  * *overdue\_reminder* - reminders sent after the invoice due date has passed in case the invoice is still unpaid.
  * *payables\_purchase\_order*
* `type` - where this template is used:
  * *email\_header* - email subject line.
  * *email\_body*
  * *memo* - a custom note to be included in the generated document. This is the text for the `memo` field in receivables or the `message` field in purchase orders.
* `template` - the actual text of a template as a plain JSON-formatted string, such as "New invoice from Acme Inc". Multiple lines can be separated by `\n`.

  The text can include [`{variables}`](/finops/guides/advanced/variables) as placeholders for customer-specific, document-specific, and organization-specific values. For example, `"Invoice {invoice_number} from {entity_name}"`.

For a list of supported variables, see [Variables](/finops/guides/advanced/variables).

## Create a template

To create a new template, call `POST /text-templates` and specify the template `name` (display name), the `document_type` this template will be used for (for example, "quote"), the template `type` (email\_header, email\_body, or memo), and the template contents as a JSON-formatted string.

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/text-templates' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "My invoice email subject",
       "document_type": "invoice",
       "type": "email_header",
       "template": "Invoice {invoice_number} from {entity_name}"
     }'
```

The response contains the `id` assigned to the created template. You can use this ID later to retrieve or update the template contents.

```json lines theme={null}
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "My invoice email subject",
  ...
  "created_at": "2023-01-20T06:18:28.660Z",
  "updated_at": "2023-01-20T06:18:28.660Z",
  "is_default": false
}
```

## Mark a template as default

Each combination of `document_type` and `type` has its default template. The default template is indicated by the `is_default` field set to `true`.

Organizations can use the default templates as-is, change them, assign other default templates, or create and use any number of custom templates.

<Info>
  **What does "default" mean?**

  It just means "*preferred* template". Note that this does not mean the default template is automatically used by Tesouro's subsystems.
</Info>

To mark a template as default, call `POST /text-templates/{text_template_id}/make-default`. This template will become the default one for its associated `document_type` and `type`.

```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/text-templates/d0207...c33/make-default' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

## Update a template

Organizations can modify the templates, including the default ones, at any time. To update a specific template, call `PATCH /text-templates/{text_template_id}`:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/text-templates/d0207...c33' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "New name",
       "template": "New contents of the template"
     }'
```

<Info>
  The `type` and `document_type` of existing templates cannot be changed. To change these fields,
  you'll have to delete the existing template and create a new one instead.
</Info>

## Delete a template

Use `DELETE /text-templates/{text_template_id}` to delete an existing text template that an organization no longer needs:

```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/v1/text-templates/d0207...c33' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

<Warning>
  Default templates cannot be deleted. Attempts to delete a default template will fail with a 409
  error.
</Warning>