Shared API Reference

These globals are bound into every cost rule, regardless of type. Rule-specific globals are documented on each rule type’s page.

`math`

Lua’s standard math module. Below is a list of commonly used math functions

Function	Returns	Description
`math.max(a, b, ...)`	number	The largest of its arguments. Handy for a floor, e.g. `math.max(0, x)`.
`math.min(a, b, ...)`	number	The smallest of its arguments. Handy for a cap, e.g. `math.min(25, x)`.
`math.abs(x)`	number	Absolute value.
`math.floor(x)`	number	Rounds down to the nearest integer.
`math.ceil(x)`	number	Rounds up to the nearest integer.

-- 0.5% of the amount, floored at 1.00 and capped at 25.00
local amount = 1000 -- Example amount
local fee = amount * 0.005
return math.min(25, math.max(1, fee))

Use math.floor / math.ceil only if the rounding is part of the pricing calculation logic. PENGINE will round any number returned according to the label’s LabelSettings.NumberOfDecimalsForCash.

For the full documentation on the math library, please see the official Lua 5.2 Reference Manual — Mathematical Functions.

`today`

The date (UTC) at which the cost rule triggered, as a date object. This is the rule’s occurrence date, so for retroactive scheduled cost rules, this can be a date in the past, yet in most scenarios this will be today.

Method	Returns	Description
`today.addDays(n)`	date	`today` shifted by `n` days.
`today.addWeeks(n)`	date	Shifted by `n` weeks.
`today.addMonths(n)`	date	Shifted by `n` months.
`today.addYears(n)`	date	Shifted by `n` years.
`today.isLeapYear()`	boolean	Whether `today`’s year is a leap year.

-- One month ago
local from = today.addMonths(-1)

Date objects are primarily used as arguments to portfolio.balancesBetween(...).

`investmentAccount`

The investment account the rule is being evaluated for

Method	Returns	Description
`investmentAccount.accountAge()`	number	Age of the account in years (fractional, floored at 0).
`investmentAccount.ownerCount()`	number	Number of owners on the account (at least 1).

-- 10.00 base fee, reduced by 1.00 per full year the account has existed
return math.max(0, 10 - investmentAccount.accountAge())

`portfolio`

Access to the investment account’s portfolio balances.

`portfolio.balancesBetween(from, till, includeCash, includeReversedCash, includeReversedUnits)`

Returns an array of numbers, 1 portfolio cash balance for each UTC day (00:00) between the from - till range.

Parameter	Type	Description
`from`	date	Start of the range (inclusive). Use a `today.*` expression.
`till`	date	End of the range (inclusive).
`includeCash`	boolean	Include cash balances.
`includeReversedCash`	boolean	Include reversed cash entries.
`includeReversedUnits`	boolean	Include reversed unit entries.

-- Average balance over the last month, charged at 0.1%
local balances = portfolio.balancesBetween(today.addMonths(-1), today, true, false, false)
local sum = 0
for _, b in ipairs(balances) do sum = sum + b end
local avg = (#balances > 0) and (sum / #balances) or 0
return avg * 0.001