Text templates

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

Overview

Entities that create invoices 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 Monite as text templates and fetched on demand. Templates can include {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 entity starts with a predefined set of templates and can also create additional templates.

List all templates

Each entity starts with a predefined set of templates. To get all available templates, call 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

Monite stores text templates in this format:

1{
2  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3  "name": "My invoice email subject",
4  "document_type": "invoice",
5  "type": "email_header",
6  "template": "Invoice {invoice_number} from {entity_name}",
7  "created_at": "2023-01-20T06:18:28.660Z",
8  "updated_at": "2023-01-20T06:18:28.660Z",
9  "is_default": false
10}

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 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} as placeholders for customer-specific, document-specific, and entity-specific values. For example, "Invoice {invoice_number} from {entity_name}".

For a list of supported variables, see 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.

1curl -X POST 'https://api.sandbox.monite.com/v1/text_templates' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN' \
5     -H 'Content-Type: application/json' \
6     -d '{
7       "name": "My invoice email subject",
8       "document_type": "invoice",
9       "type": "email_header",
10       "template": "Invoice {invoice_number} from {entity_name}"
11     }'

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

1{
2  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
3  "name": "My invoice email subject",
4  ...
5  "created_at": "2023-01-20T06:18:28.660Z",
6  "updated_at": "2023-01-20T06:18:28.660Z",
7  "is_default": false
8}

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.

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

What does “default” mean?

It just means “preferred template”. Note that this does not mean the default template is automatically used by Monite’s subsystems.

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.

1curl -X POST 'https://api.sandbox.monite.com/v1/text_templates/d0207...c33/make_default' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

Update a template

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

1curl -X PATCH 'https://api.sandbox.monite.com/v1/text_templates/d0207...c33' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN' \
5     -H 'Content-Type: application/json' \
6     -d '{
7       "name": "New name",
8       "template": "New contents of the template"
9     }'

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.

Delete a template

Use DELETE /text_templates/{text_template_id} to delete an existing text template that an entity no longer needs:

1curl -X DELETE 'https://api.sandbox.monite.com/v1/text_templates/d0207...c33' \
2     -H 'X-Monite-Version: 2023-09-01' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

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