FI List of Placeholder variables for templates

The following list of variables are useful when adapting the finance document template.  These variables can be included into templates and represent varying values of financial data. This is not the complete list, but generally speaking these are the most frequent ones. 

Other variables can be inserted into templates using a line like:
<H1><%= %variable_name% ></H1>
You can also make function calls from templates and set your own template specific variables:
<% set rate [im_exchange_rate $invoice_date EUR USD] %>
<%=[lc_time_fmt $calculated_due_date "%e. %B %Y" en_EN]%>

If the resulting string contains XML special characters, you want to make sure that you escape them.

Please note that in the lists below that invoice is meant to refer to all financial documents. Variables are presented alphabetically by variable name.  

General Variables 

  • default_currency - defines the "DefaultCurrency" parameter   
  • internal_contact_email - email of user_id
  • internal_contact_name - name of user_id
  • total_due - Subtotal + VAT + TAX
  • total_due_pretty - formatted total_due
  • locale - The locale of this invoice, determined by the name of the invoice template. For example "invoice.en_US.adp" will lead to an "en_US" locale for this financial document.  The "locale" determines the language of static texts and the formatting of numbers.
  • page_title - The HTML title of the invoice. Just for the browser header (usually not printed)
  • rounding_precision - Constant set to "2". Determines the number of digits of rounding precision for subtotals etc.
  • subtotal_pretty - formatted subtotal
  • subtotal - subtotal (sum of invoice items)
  • user_id - the ID of the current user (currently looking at the page)
  • user_locale - The default locale of the current user is, in general, different from  locale. This locale serves as a fallback value in case that there is no locale defined for the invoice.

Related Projects

These variables are useful if you want to refer one or more projects that are related to the given invoice. Please note that you can have 0, 1 or multiple projects related to a single invoice (0 for a "stand-alone" invoice without project, 1 for the standard case of one project per invoice and multiple projects if you choose to do "cumulative invoicing", where you include several (small) projects in a single invoice).

  • num_related_projects - Number of related projects, e.g.: 0, 1 or more.
  • related_customer_project_nrs - TCL list of the customer's project references to the related projects.
  • related_projects -  Project ID's of related projects.
  • related_project_names - Project Names of related projects.
  • related_project_nrs - The TCL list of the "numbers" of related projects. Please use <%= [join $related_project_nrs ", "] %> to use this field in the template, so that multiple projects are displayed correctly with a ", " in between.

Customer and Provider

A Financial Document is usually between the "internal company" (please see above) and either a Provider or a Customer, depending on the type of financial document. "Company" in this context refers to this 2nd party, independently of whether it's a customer or a provider.

  • accounting_contact_id - ID of the company's accounting contact person.
  • company_id - ID of the customer or provider
  • company_name - (Long name)
  • company_path - Path  (short name)
  • company_status_id - Status of the company. Use select im_category_from_id (company_status_id) to get a human readable status
  • company_type_id - Type of company. See company_status_id above for formatting.
  • crm_status_id - Information about the CRM acquisition process.
  • deleted_p - The company may already have been deleted…
  • primary_contact_id - ID of the company's main contact person. Please use select im_name_from_user_id (:primary_contact_id) to obtain the name and select im_email_from_user_id(:primary_contact_id) to obtain the contact's email.
  • vat_number - The VAT number of company 

The following fields contain information about the preferences/default values for the company's payment conditions and templates for different invoice types. 

  • default_bill_template_id
  • default_delnote_template_id
  • default_invoice_template_id
  • default_payment_days
  • default_payment_method_id
  • default_po_template_id
  • default_vat

Information about the company's "Office" selected for this invoice. Please note that there can be several Offices per company, so this one refers to the particular office defined in the invoice.

  • address_city
  • address_country_code - Two digit code for the country
  • address_line1 - first of two address lines
  • address_line2 - second of two address lines
  • address_postal_code - ZIP
  • address_state - May only be useful for US American addresses.
  • country_name - English name of the country (can be localized)
  • fax
  • office_id - ID
  • office_name - Name of the Office. Can be used to designate a company's sub organization (department, …) if suitably maintained in the customer's file
  • office_path - Short name of the office
  • office_status_id - Status (as usual)
  • office_type_id - Type (as usual)

Financial Items

  • calculated_due_date - due date (effective date + payment days)company_contact_email - Email of company_contact_id
  • calculated_due_date_pretty - due date formatted according to locale
  • effective_date - effective date of invoice
  • company_contact_id - ID of the Customer's/Provider's contact person to who we want to send or direct the financial document
  • company_contact_name - Name of company_contact_id
  • cost_center_id - Cost Center/Department
  • cost_center_name - Long name CC/Dept
  • cost_note - Note (prominent field in InvoiceListPage and Template)
  • cost_status - Status (human readable)
  • cost_status_id - Status (ID)
  • cost_type - human readable ID
  • cost_type_id - Type (ID)
  • customer_id - Customer, either the "internal" company for a bill/po or customer company for an invoice/quote/delivery note.
  • provider_id - Provider, either the "internal" company for an invoice/quote or the provider company for a bill/po.
  • invoice_date - same as effective date
  • invoice_date_pretty - effective date formatted
  • invoice_office_id - company's office ID
  • invoice_or_bill_p - True ("1") if financial item is a customer invoice or a provider bill. Both types are "hard costs" and require certain fields such as payment conditions.
  • invoice_or_quote_p - True ("1") if the document is related to a Customer (as opposed to Provider). Also true for "Delivery Note".
  • invoice_payment_method - short human readable text for payment method such as "Bank ABC"
  • invoice_payment_method_id - same as payment_method_id
  • invoice_payment_method_desc - Long description text for payment method detailing the how the money should be paid, typically including the bank name, SWIFT code, IBAN, account number, etc.
  • invoice_status_id - same as cost_status_id
  • invoice_template_id - Rendering template for the cost item.
  • item_currency - Currency of invoice items
  • paid_amount - registered payments for this cost item, converted into paid_currency
  • paid_currency - currency of payments, usually identical with default_currency
  • payment_days - number of days for payment, difference between effective_date and calculated_due_date
  • payment_method_id - ID that determines payment details
  • tax - TAX (percentage). This field can accommodate applicable tact, for example Spanish IRPF, or sales tax
  • tax_amount - TAX (percentage x invoice amount)
  • tax_amount_pretty - TAX (percentage x invoice amount) formatted
  • vat - VAT (percentage)
  • vat_amount - VAT (percentage x invoice amount)
  • vat_amount_pretty - VAT (percentage x invoice amount) formatted

Currency and Date Formatting

These formats are used on the SQL level to format variables. The format depends on the locale parameter (see above). For further customization (modifying the decimal and thousand separators for a particular locale) you can modify the language definition files in the "catalog" folder of the acs-lang package. Please see the OpenACS documentation for more details.

  • cur_format
  • tax_format
  • vat_format

Pre-formatted Pieces of HTML

These are pieces of HTML are already formatted to be included in the InvoiceViewPage and the template.  You can customize these elements by using a StyleSheet.

  • item_html
  • item_list_html
  • invoice_item_html
  • payment_list_html - List of related payments formatted for the ViewPage (not for the Preview)
  • payment_method_html
  • payment_terms_html - Formatted "payment conditions" section. Usually only applicable for "hard costs" where invoice_or_bill_p == true (see below).
  • note_html
    Preformatted (<pre>...</pre>) invoice "note" field
  • render_template_id
    ID of the display template to be used for rendering. Refers to the category_id field in the im_categories table where you find the actual name of the template in the "category" field.
  • subtotal_item_html
    The formatted piece of HTML representing the "subtotal" section with subtotal, VAT, TAX and grand total.







Available since Version

Internal information


Company name


Foo Company



First address line


Foo street 1




Second address line


14th floor




Postal code












Country code






Phone no.


+12 123 12345678




Fax no.


+12 123 12345679




E-Mail address of your primary contact




VAT ID-Number




Customer information


Company name


Big Customer Inc.




Salutation for contact person






Contact person’s name


Peter Jung




Contact person’s position






Address line 1


Rich Avenue 1




Address line 2


1st – 3rd floor




Postal code












Customer no.




Finance doc information


Invoice date (localized format)






Invoice No.






Counter for invoiced positions






No. of units (localized format)
Note: This is a MANDATORY field *






Unit of measurement


Lines, Words, Hours, etc.


Currency of invoice items

EUR, GBP, USD, etc.



Item name






Price for one unit (localized format, no currency symbol added)
Note: This is a MANDATORY field *






Summed amount for this line (localized format, no currency symbol added)






VAT percentage rate (without %-symbol)






VAT amount (localized format, no currency symbol)






Grand total of invoice (localized format, no currency symbol)




* These fields are mandatory. If they are not part of the template, you'll receive either error messages or incorrect variable substitution. You can prevent their appearance by choosing a white font color. 


  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

E-08907 Hospitalet de Llobregat (Barcelona)

 Tel Europe: +34 932 202 088
 Tel US: +1 415 429 5995