> ## 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.

# Template variables

> Learn how to use variables to parameterize your invoice notes and email messages.

## Overview

Variables are named placeholders in strings that are later replaced with actual values. For example, if you want to add an invoice note addressing the counterpart (customer) personally, you can use the `{company_name}` variable in the note text and Tesouro will automatically substitute it with the counterpart name associated with that invoice.

Variables can be used in any of the following ways:

* The `memo` and `footer` fields of [accounts receivable](/finops/guides/accounts-receivable/index) invoices, quotes, and credit notes.
* [Email templates](/finops/guides/advanced/email-templates/index)
* [Text templates](/finops/guides/advanced/text-templates)
* The email subject and body when sending documents via email by using the following endpoints:
  * [`POST /receivables/{receivable_id}/send`](/finops/reference/openapi/receivables/post-receivables-id-send)
  * [`POST /payable-purchase-orders/{purchase_order_id}/send`](/finops/reference/openapi/purchase-orders/post-payable-purchase-orders-id-send)

## Specifics of using variables in `memo` and `footer` fields

Variables inserted into the text of the `memo` and `footer` fields are **immediately substituted** with their values. That is, the replacement happens immediately during the document creation (POST) or update (PATCH), rather than later when the document gets issued.

Keep this in mind when repeatedly updating draft documents, as the `memo` text with earlier substitutions might no longer reflect the current values of the variables.

<Accordion title="Example">
  Consider a draft invoice created for a [counterpart](/finops/guides/common/counterparts/index) named Trustwave.

  If you add an invoice `memo` containing the `{company_name}` (counterpart name) variable:

  ```sh lines theme={null}
  curl -X PATCH 'https://api.sandbox.tesouro.com/v1/receivables/4ba6...03178f' \
       -H 'X-Finops-Version: 2025-06-23' \
       -H 'X-Organization-Id: ORGANIZATION_ID' \
       -H 'Authorization: Bearer ACCESS_TOKEN' \
       -H 'Content-Type: application/json' \
       -d '{
         "invoice": {
           "memo": "Thanks for doing business with us, {company_name}!"
         }
       }'
  ```

  the returned `memo` value will contain the hard-coded counterpart name:

  ```json lines theme={null}
  {
    "type": "invoice",
    "id": "4ba6c23b-44a6-459f-9211-c45c7d03178f",
    ...
    "memo": "Thanks for doing business with us, Trustwave!"
  }
  ```

  But if you then change the `counterpart_id` for this invoice, the `memo` will still contain the old counterpart name.

  To avoid issues, you can use these approaches:

  * Add `memo` and `footer` as the last update before issuing the document.
  * When calling `PATCH /receivables/{receivable_id}` to update draft documents, provide the `memo` and `footer` values containing `{variables}` to ensure the resulting formatted strings remain up-to-date.
</Accordion>

## Retrieving variables

Certain variables are document-specific and can only be used on a particular document. You can retrieve variables depending on the document type. Tesouro provides separate endpoints to retrieve Payable, Purchase order, and Receivable document variables.

### Payables

To retrieve variables associated with Payables, call [`GET /payables/variables`](/finops/reference/openapi/payables/get-payables-variables):

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

The successful response returns an object containing an array of variable names and descriptions associated with payables.

### Purchase orders

To retrieve variables associated with Purchase order documents, call [`GET /payable-purchase-orders/variables`](/finops/reference/openapi/purchase-orders/get-payable-purchase-orders-variables):

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/payable-purchase-orders/variables' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
```

The successful response returns an object containing an array of variable names and descriptions associated with purchase orders.

### Receivables

To retrieve variables associated with Accounts Receivable documents, call [`GET /receivables/variables`](/finops/reference/openapi/receivables/get-receivables-variables):

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

The successful response returns an object containing an array of variable names and descriptions associated with each receivable document type (invoices, quotes, credit notes, etc.) and invoice reminders.

## Variable list

When retrieving document variables, their responses include an `object_type` and `object_subtype` field that differentiates each document type.

The following table shows the `object_type` values and their corresponding possible `object_subtype` values and descriptions:

| `object_type`  | `object_subtype`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"receivable"` | `"invoice"`<br />`"quote"`<br />`"credit_note"`                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `"reminder"`   | <p>`"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 has not been fully paid.</p><p>`"final_reminder"` - payment reminder sent before the invoice due date.</p><p>`"overdue_reminder"` - [reminders](/finops/guides/accounts-receivable/invoices/overdue-reminders) sent after the invoice due date has passed in case the invoice has not been fully paid.</p> |

### Common variables

These variables are available for all document types, unless noted otherwise:

| Variable                   | Description                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{company_email}`          | The email address of the counterpart.                                                                                                                                                                                                                                                                                                                               |
| `{company_name}`           | The counterpart name (either the company name or an individual's name).                                                                                                                                                                                                                                                                                             |
| `{contact_email}`          | <p>The email address of the counterpart's default contact. If no contacts are defined, the counterpart's email address is used instead.</p><p>**Note:** This variable exists only if the counterpart is an organization.</p>                                                                                                                                        |
| `{contact_name}`           | <p>The name of the counterpart's default contact. If no contacts are defined, the counterpart name is used instead.</p><p>**Note:** This variable exists only if the counterpart is an organization.</p>                                                                                                                                                            |
| `{currency}`               | <p>3-letter currency code. For example, USD.</p><p>**Note:** This variable is not available for purchase orders.</p>                                                                                                                                                                                                                                                |
| `{currency_symbol}`        | <p>The currency symbol. For example, \$.</p><p>**Note:** This variable is not available for payables and purchase orders.</p>                                                                                                                                                                                                                                       |
| `{entity_email}`           | The email address of the organization, as specified by the `email` field of the `Entity` object.                                                                                                                                                                                                                                                                    |
| `{entity_logo}`            | The logo of the organization. This value can be set via the [`PUT /identity/v1/organizations/{organizationId}/logo`](/finops/reference/openapi/identity/uploads-a-logo-for-an-organization) endpoint.                                                                                                                                                               |
| `{entity_name}`            | The name of the organization.                                                                                                                                                                                                                                                                                                                                       |
| `{entity_website}`         | <p>The URL of the organization's website, as specified by the `website` field of the `Entity` object.</p><p>**Note:** This variable is only available in [email templates](/finops/guides/advanced/email-templates/index).</p>                                                                                                                                      |
| `{footer}`                 | <p>The text of the document's `footer` field.</p><p>**Note:** This variable is not available for payables and purchase orders.</p>                                                                                                                                                                                                                                  |
| `{memo}`                   | <p>The text of the document's `memo` field.</p><p>**Note:** This variable is not available for payables and purchase orders.</p>                                                                                                                                                                                                                                    |
| `{partner_metadata.<key>}` | <p>The value of the specified key from a document's [metadata](/finops/guides/common/metadata). For more information, see [Using metadata in email templates](/finops/guides/common/metadata#email-templates).</p><p>**Note:** These variables are supported only for receivables and only in [email templates](/finops/guides/advanced/email-templates/index).</p> |
| `{total_value}`            | The invoice subtotal (without tax), formatted with cents but without the currency sign. For example, `50.00`. See also `{amount_due}`.                                                                                                                                                                                                                              |

### Additional variables for payables

In addition to the [common variables](#common), payables can use the following variables:

| Variable              | Description                                                                             |
| --------------------- | --------------------------------------------------------------------------------------- |
| `{customer_name}`     | The customer name, as returned by the `counterpart_name` value of the `Payable` object. |
| `{document_id}`       | The value returned on the `document_id` field of the `Payable` object.                  |
| `{due_date}`          | The value returned on the `due_date` field of the `Payable` object.                     |
| `{invoice_id}`        | The value returned on the `id` field of the `Payable` object.                           |
| `{total_amount}`      | The value returned on the `amount` field of the `Payable` object.                       |
| `{uploaded_username}` |                                                                                         |

### Additional variables for purchase orders

In addition to the [common variables](#common), purchase orders can use the following variables:

| Variable                         | Description                                                                                                              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `{issue_date}`                   | The date when the purchase order was issued.                                                                             |
| `{payables_purchase_order_link}` | The URL of the PDF version of the purchase order, as returned by its `file.url` property.                                |
| `{purchase_order_number}`        | The purchase order number, as returned by the `document_id` value of the `Receivable` object.                            |
| `{total_amount}`                 | Calculated from `purchase_order.items` and converted to minor units based on the currency.                               |
| `{total_amount_with_tax}`        | Calculated from `purchase_order.items` and converted to minor units based on currency and includes the tax of the items. |
| `{validity_date}`                | Calculated as the date of today plus the value `purchase_order.valid_for_days`.                                          |

### Additional variables for invoices

In addition to the [common variables](#common), outgoing invoices can use these variables:

| Variable             | Description                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| `{amount_due}`       | The total invoice amount (including tax). For example, `611.25`. See also `{total_value}`.                      |
| `{due_date}`         | The invoice due date, as returned by the `due_date` field of the `Receivable` object.                           |
| `{fulfillment_date}` | The invoice fulfillment date, as specified by the corresponding property of the `Receivable` object.            |
| `{invoice_link}`     | The URL of the PDF version of the invoice, as returned by the `file.url` property of the `Receivable` object.   |
| `{invoice_number}`   | The invoice number, as returned by the `document_id` property of the `Receivable` object.                       |
| `{issue_date}`       | The date when the invoice was issued.                                                                           |
| `{payment_link}`     | The URL of the invoice payment page, as returned by the `payment_page_url` property of the `Receivable` object. |
| `{total_value}`      | The invoice subtotal (without tax). For example, `600.00`. See also `{amount_due}`.                             |

### Additional variables for quotes

In addition to the [common variables](#common), quotes can use the following variables:

| Variable         | Description                                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `{issue_date}`   | The date when the quote was issued.                                                                                          |
| `{payment_link}` | A URL that points to the quote accept/decline page, as specified by the `quote_accept_url` field of the `Receivable` object. |
| `{quote_link}`   | The URL of the PDF version of the quote, as returned by the `file.url` property of the `Receivable` object.                  |
| `{quote_number}` | The quote number, as returned by the `document_id` value of the `Receivable` object.                                         |
| `{total_value}`  | The quote subtotal (without tax). For example, `600.00`.                                                                     |

### Additional variables for credit notes

In addition to the [common variables](#common), credit notes can use these variables:

| Variable                 | Description                                                                                                       |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `{amount_due}`           |                                                                                                                   |
| `{based_on_amount_due}`  |                                                                                                                   |
| `{based_on_document_id}` | The `document_id` value of the invoice for which the credit note was created.                                     |
| `{credit_note_link}`     | The URL of the PDF version of the credit note, as returned by the `file.url` property of the `Receivable` object. |
| `{credit_note_number}`   | The credit note number, as returned by the `document_id` value of the `Receivable` object.                        |
| `{due_date}`             |                                                                                                                   |
| `{fulfillment_date}`     |                                                                                                                   |
| `{issue_date}`           | The date when the credit note was issued.                                                                         |
| `{total_value}`          |                                                                                                                   |

### Additional variables for invoice reminders

Variables for invoice reminders are available in the response from the `GET /receivable/variables` endpoint. These variables have an `object_type` value of `reminder`. The possible `object_subtype` value for these variables include `discount_reminder`, `final_reminder`, and `overdue_reminder`.

#### Payment reminders

Payment reminders refer to reminder emails sent to a counterpart before the invoice's due dates and early discount dates. In addition to the [common variables](#common), invoice payment reminders can include the following variables in their email subject and body.

| Variable                  | Description                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `{amount_due}`            |                                                                                                               |
| `{document_id}`           | The invoice number, as returned by the `document_id` property of the `Receivable` object.                     |
| `{due_date}`              | The invoice due date, as returned by the `due_date` field of the `Receivable` object.                         |
| `{fulfillment_date}`      |                                                                                                               |
| `{invoice_link}`          | The URL of the PDF version of the invoice, as returned by the `file.url` property of the `Receivable` object. |
| `{invoice_number}`        | The invoice number, as returned by the `document_id` property of the `Receivable` object.                     |
| `{issue_date}`            | The date when the invoice was issued.                                                                         |
| `{payment_link}`          |                                                                                                               |
| `{payment_term_discount}` |                                                                                                               |
| `{total_value}`           |                                                                                                               |

#### Overdue reminders

In addition to the [common variables](#common), overdue reminders can include the following variables in their email subject and body:

| Variable                  | Description                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `{amount_due}`            |                                                                                                               |
| `{document_id}`           | The invoice number, as returned by the `document_id` property of the `Receivable` object.                     |
| `{due_date}`              |                                                                                                               |
| `{fulfillment_date}`      |                                                                                                               |
| `{invoice_link}`          | The URL of the PDF version of the invoice, as returned by the `file.url` property of the `Receivable` object. |
| `{invoice_number}`        | The invoice number, as returned by the `document_id` property of the `Receivable` object.                     |
| `{issue_date}`            | The date when the invoice was issued.                                                                         |
| `{payment_link}`          |                                                                                                               |
| `{payment_term_discount}` |                                                                                                               |
| `{total_value}`           |                                                                                                               |