Using calculations in offer letters

How calculations in offer letters work

The following calculations can be used in offer letter templates:

• Addition
• Subtraction
• Multiplication
• Division
• Modulo (i.e. calculating the remainder)

These calculations can only be used in conjunction with offer fields corresponding to currency and number values on the offer form. In the formulas that write into your offer letter templates, offer field values need to be defined as numbers in order for the calculation to be performed. Additionally, offer fields values with a 'Currency' field type need to be converted back to currency as part of the calculation so that resulting value in the offer letter is presented to exactly two decimal places and with the currency code. Refer to the following examples to better understand the distinction between number and currency value calculations.

Example: Number value calculation
Consider an example where offered equity must be multiplied by a fixed rate. In this example, the offered equity is 5000 shares.

'Offered equity' field as it appears on the offer form

In this case, the 'Offered equity field corresponds to the {offered_equity} placeholder (Super Admins can find offer fields and their corresponding placeholder by navigating to Settings > Offers > Offer fields). This offer field has a 'Number' field type.

'Offered equity' offer field, including placeholder and field type in Settings > Offers > Offer fields

The fixed rate multiple for the offered equity is 1.15. Essentially, the calculation to be performed is:

{offered_equity} * 1.15

However, recall that offer field values need to be defined as numbers in order for calculations to be performed. In this example, the value in the {offered_equity} placeholder can be defined as a number by making the following adjustment to the calculation:

{number(offered_equity) * 1.15)}

With this calculation, the value that would appear on the offer letter is 5750.

Example: Currency value calculation
Consider an example where the offered compensation that appears in a candidate's offer letter must be increased by a fixed amount. For this example, the offered compensation is $100,000.00 USD paid annually.

'Offered compensation amount' field as it appears on the offer form

In this case, the 'Offered compensation amount' field corresponds to the {salary_amount} placeholder (Super Admins can find offer fields and their corresponding placeholder by navigating to Settings > Offers > Offer fields). This offer field has a 'Currency' field type.

'Offered  compensation amount' offer field, including placeholder and field type in Settings > Offers > Offer fields

The number to be added to the salary is 5125.5. Essentially, the calculation to be performed is

{salary_amount} + 5125.5

However, recall that offer field values need to be defined as numbers in order for calculations to be performed. In this example, the value in the {salary_amount} placeholder can be defined as number by making the following adjustment to the calculation:

{number(salary_amount) + 5125.5}

If the final value that we wanted to appear on the offer was a number, we could stop here. Were we to stop with the example at this step, the value that would appear on the offer letter is 105,125.5 (i.e. 100,000 + 5125.5). However, we want this value to appear as a currency on the offer letter (i.e. a number presented to exactly two decimal places with the currency code). Therefore, we need to augment the calculation further to show the final value as a currency:

{currency(number(salary_amount) + 5125.5)}

With this calculation, the value that would appear on the offer letter is $105,125.50. 

Below you will find a breakdown of how to write out each calculation in an offer letter template to produce either a number or currency value. In the example formulas shown, the placeholders {offered_equity) and {salary_amount} are used as examples of offer fields of the 'Number' and 'Currency' field types respectively. Consider {offered_equity) to be equal to 5000 shares and {salary_amount} to be equal to $100,000.00. When writing out calculations of our own, you can use any offer field of a numeric or currency field type (see additional examples in the second section of this article).

Troubleshooting errors with offer letter calculations
Refer to the following guidelines to prevent the calculations in your offer letter from resulting in errors or incorrect values:

• Calculations are space sensitive. You must have exactly one space on either side of the operator in order for the calculation to function correctly.
• If you are creating an offer template in Microsoft Word, note that the subtraction sign (-) will convert to a long dash (—) if there are two spaces trailing instead of one.
• Calculations that result in a value equal to zero or a negative number will cause an error.
• Calculation are performed in the order in which they are written (not the mathematical order of operations).
• If a number is not converted to a currency as part of the calculation, the result of the calculation will be interpreted to its fullest length including all numbers that might appear after the decimal.

Examples of calculations in offer templates

Here's an example of a paragraph in an offer letter template that uses calculations to provide a monthly breakdown of the salary being offered to a candidate, adjusted for a 5% benefits deduction (calculations are bolded for emphasis only).

Your gross monthly pay amounts to {currency(number(salary_amount) / 12)}. Adjusted for benefits deductions, your monthly net pay amounts to {currency((number(salary_amount) / 12)*0.95)}.

Here's an example of a paragraph in an offer letter template describing the employer's extension of the option to match contributions to the incumbent employee's pension fund to a maximum of 8% of their annual salary, broken down by month.

In addition to your salary, you retain the option opt-in to annual pension contribution matching, wherein the organization will match contributions you make to your pension fund to maximum of {currency(number(salary_amount) * 0.08)} annually, or {currency((number(salary_amount) * 0.08) / 12)} per month.

Here's an example of a line in an offer letter template that uses addition to combine two variable amounts - offered salary and a custom superannuation amount.

Your total compensation amounts to {currency(number(salary_amount) + (number(custom_superannuation))}.