Variables

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),
the email subject and body when sending documents via email by using the following endpoints:
- POST /receivables/{receivable_id}/send
- POST /payable_purchase_orders/{purchase_order_id}/send
text templates.

Specifics of using variables in `memo` fields

Variables 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-03-14' \
     -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 the memo value containing {variables} to ensure that the memo 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 that created the invoice.
`{entity_name}`	The name of the entity that created the quote.
`{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 invoice subtotal (without VAT) formatted with the currency code. For example, `50.00 €`. See also `{total_value}`.
`{due_date}`	The invoice due date, as returned by the `payment_terms.term_final.end_date` field of the `Receivable` object.
`{fulfilled_date}`	Unused. Reserved for future use.
`{invoice_link}`	A link to 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}`	A secure payment link that the counterpart can use to pay the invoice.
`{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 quotes

In addition to the common variables, quotes can use these variables:

Variable	Description
`{fulfilled_date}`	Unused.
`{issue_date}`	The date when the quote was issued.
`{payment_link}`	Unused.
`{quote_link}`	A link to 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), formatted with cents but without the currency sign. For example, $50 is represented as `50.00`.

Additional variables for credit notes

In addition to the common variables, credit notes can use these variables:

Variable	Description
`{amount_due}`
`{amount_of credit note}` (note the spaces in the name)
`{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}`	A link to the PDF version of the credit note, as returned by the `file.url` property of the `Receivable` object.
`{credit_note number}` (note the space in the name)	The credit note number, as returned by the `document_id` value of the `Receivable` object.
`{fulfillment_date}`
`{invoice_number}`	The `document_id` value of the invoice for which the credit note was created.
`{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}`	A link to 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 under object_type= "discount_reminder" and "final_reminder".

Variable	Description
`{amount_due}`
`{currency}`
`{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}`	A link to 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}`	Unused.
`{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}`
`{document_id}`	The invoice number, as returned by the `document_id` property of the `Receivable` object.
`{due_date}`
`{fulfillment_date}`
`{invoice_link}`	A link to 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}`	Unused.
`{payment_term_discount}`
`{total_value}`

Overview

Specifics of using variables in memo fields

Variable list

Common variables

Additional variables for invoices

Additional variables for quotes

Additional variables for credit notes

Additional variables for purchase orders

Additional variables for invoice reminders

Payment reminders

📘

Overdue reminders

Specifics of using variables in `memo` fields