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 Monite will automatically substitute it with the counterpart name associated with that invoice.
Variables can be used in:
- the
memo
field of Accounts Receivable documents (invoices, quotes, credit notes), - email templates
- the email subject and body when sending documents via email by using the following endpoints:
- text templates,
Specifics of using variables in memo
fields
memo
fieldsVariables inserted into the memo
text of invoices, quotes, or credit notes 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.
Example
Consider a draft invoice created for a counterpart named Trustwave.
If you add an invoice memo
containing the {company_name}
(counterpart name) variable:
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/4ba6...03178f' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_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:
{
"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
as the last update before issuing the document. - When calling
PATCH /receivables/{receivable_id}
to update draft invoices, provide thememo
value containing{variables}
to ensure that thememo
remains up-to-date.
Variable list
A list of available variables is provided below for convenience.
To get the available variable names programmatically, you can call GET /text_templates/variables
. In the response, the variables are grouped by their object_type
and subtype
:
{
"data": [
{
"object_type": "receivable",
"object_subtype": "quote",
"variables": [
{
"name": "fulfillment_date",
"description": ""
},
...
]
},
{
"object_type": "receivable",
"object_subtype": "invoice",
"variables": [
{
"name": "amount_due",
"description": ""
},
...
]
},
{
"object_type": "receivable",
"object_subtype": "credit_note",
"variables": [
{
"name": "amount_due",
"description": ""
},
...
]
},
{
"object_type": "reminder",
"object_subtype": "discount_reminder",
"variables": [
{
"name": "amount_due",
"description": ""
},
...
]
},
{
"object_type": "reminder",
"object_subtype": "final_reminder",
"variables": [
{
"name": "amount_due",
"description": ""
},
...
]
},
{
"object_type": "reminder",
"object_subtype": "overdue_reminder",
"variables": [
{
"name": "amount_due",
"description": ""
},
...
]
},
{
"object_type": "payable",
"object_subtype": "payables_purchase_order",
"variables": [
{
"name": "company_email",
"description": ""
},
...
]
}
]
}
Possible object_type
and subtype
values are:
object_type | subtype |
---|---|
"receivable" | "invoice" "quote" "credit_note" |
"reminder" | "discount_reminder" - invoice payment reminders sent before the first and second early payment dates (if any) if the invoice has not been fully paid. "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 has not been fully paid. |
"payable" | "payables_purchase_order" |
Common variables
These variables are defined for all document types:
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} | The email address of the counterpart's default contact. If no contacts are defined, the counterpart's email address is used instead. Note: This variable exists only if the counterpart is an organization. |
{contact_name} | The name of the counterpart's default contact. If no contacts are defined, the counterpart name is used instead. Note: This variable exists only if the counterpart is an organization. |
{entity_email} | The email address of the entity, as specified by the email field of the Entity object. |
{entity_name} | The name of the entity. |
{entity_website} | The URL of the entity's website, as specified by the website field of the Entity object.Note: This variables is only available in email templates. |
{total_value} | The invoice subtotal (without VAT), formatted with cents but without the currency sign. For example, 50.00 . See also {amount_due} . |
Additional variables for invoices
In addition to the common variables, outgoing invoices can use these variables:
Variable | Description |
---|---|
{amount_due} | The total invoice amount (including VAT). For example, 611.25 . See also {total_value} . |
{currency} | Invoice currency as a 3-letter currency code. For example, EUR. |
{due_date} | The invoice due date, as returned by the payment_terms.term_final.end_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 VAT). For example, 600.00 . See also {amount_due} . |
Additional variables for quotes
In addition to the common variables, quotes can use these variables:
Variable | Description |
---|---|
{currency} | The currency of the quote, as a 3-letter currency code. For example, EUR. |
{fulfilled_date} | Unused. |
{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 VAT). For example, 600.00 . |
Additional variables for credit notes
In addition to the common variables, 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. |
{currency} | Credit note currency, as a 3-letter currency code. For example, EUR. |
{due_date} | |
{fulfillment_date} | |
{issue_date} | The date when the credit note was issued. |
{payment_link} | Unused. |
{total_value} | . |
Additional variables for purchase orders
In addition to the common variables, purchase orders can use these 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} | |
{total_amount_with_vat} | |
{validity_date} |
Additional variables for invoice reminders
Payment reminders
In addition to the common variables, invoice payment reminders can include the following variables in their email subject and body.
In the response from
GET /text_templates/variables
, these variables are grouped underobject_type
= "discount_reminder" and "final_reminder".
Variable | Description |
---|---|
{amount_due} | |
{currency} | Invoice currency, as a 3-letter currency code. For example, EUR. |
{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 payment_terms.term_final.end_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, overdue reminders can include the following variables in their email subject and body:
Variable | Description |
---|---|
{amount_due} | |
{currency} | Invoice currency, as a 3-letter currency code. For example, EUR. |
{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} |
Updated 21 days ago