Formula tags
Formula tags compute numeric values automatically based on the values of other tags on the document. The result updates in real time as recipients fill in the tags your formula references.
Use formula tags to display calculated totals, subtotals, tax amounts, or any derived value without requiring recipients to calculate or enter them manually.
Common use cases:
- Invoice totals: multiply quantity by unit price
- Tax lines: multiply a subtotal by a fixed rate
- Grand totals: sum multiple line items
- Duration calculations: compute the difference between two numeric values
How formula tags work
When a recipient fills in a number tag that a formula references, the formula recalculates immediately and displays the new result. Formula tags are read-only — recipients see the computed value but cannot edit it directly.
Formula tags are evaluated during live signing. In the template editor preview, the formula expression itself is shown in place of a calculated value.
Formula syntax
Formulas reference other tags by their data label using bracket notation and combine them with standard arithmetic operators.
Field references
Use square brackets to reference another tag by its data label:
[TagLabel]
The label must match the referenced tag's Label property exactly. Labels are case-sensitive — [UnitPrice] and [unitprice] are treated as different references.
Note: Only Number tags can be referenced in a formula. Text, Date, Dropdown, and other tag types cannot be used as formula inputs.
Arithmetic operators
| Operator | Operation | Example |
|---|---|---|
+ | Addition | [Subtotal] + [Tax] |
- | Subtraction | [Price] - [Discount] |
* | Multiplication | [Quantity] * [UnitPrice] |
/ | Division | [TotalCost] / [NumPeople] |
( ) | Grouping | ([Price] * [Quantity]) - [Discount] |
Operators follow standard arithmetic precedence: multiplication and division are evaluated before addition and subtraction. Use parentheses to control evaluation order explicitly.
Literal numbers
You can include literal numeric values directly in a formula:
[Subtotal] * 0.08
[Hours] * 150
([Price] * [Quantity]) * 1.1
Configuration
Configure formula tags in the Formula Settings section of the properties panel.
Formula expression
The expression field holds the formula. Enter field references and operators to define the calculation.
[Quantity] * [UnitPrice]
The properties panel shows a list of available number tags you can click to insert directly into the expression, reducing the chance of a label typo.
Decimal places
Controls how many decimal places the result is rounded to before display.
| Setting | Result for 1 / 3 |
|---|---|
0 | 0 |
2 | 0.33 |
4 | 0.3333 |
The default is 2. Choose 0 for whole-number results such as counts or IDs. Choose higher values for scientific or financial calculations that require precision.
Fallback value
The value to display when the formula cannot be evaluated — for example, when a referenced tag has not been filled in yet.
Leave this blank to show nothing until the formula has a valid result. Set it to a string such as "—" or "0.00" if you want a placeholder visible from the start.
Hidden field
When enabled, the formula calculates normally but the result is not displayed on the document. Use this when you need an intermediate computed value that other formulas reference but that should not be visible to recipients.
Example formulas
Invoice line total
Multiply quantity by unit price:
[Quantity] * [UnitPrice]
Required number tags: Quantity, UnitPrice
Subtotal with discount
Subtract a discount from the line total:
([Quantity] * [UnitPrice]) - [Discount]
Required number tags: Quantity, UnitPrice, Discount
Tax amount
Calculate sales tax at a fixed rate:
[Subtotal] * 0.08
Required number tags: Subtotal
Grand total
Sum subtotal and tax:
[Subtotal] + [Tax]
Required number tags: Subtotal, Tax
Per-person cost
Divide a total evenly:
[TotalCost] / [NumPeople]
Required number tags: TotalCost, NumPeople
Dependency tracking
Formula tags automatically track which tags they depend on. When a referenced tag's value changes during signing, every formula that references it recalculates immediately. You do not need to configure this — it happens automatically based on the labels you use in the expression.
When you select a formula tag in the template editor, the tags it references are highlighted on the document to make the dependency visible.
Troubleshooting
Formula shows the fallback value
The formula cannot be evaluated. Check the following:
- Label mismatch — The label in the formula expression does not match the label on the referenced tag. Labels are case-sensitive. Open the referenced tag's properties and confirm the label matches exactly, including capitalization.
- Referenced tag has no value — The formula waits until all referenced tags have values before calculating. This is expected behavior during signing.
- Referenced tag is not a number tag — Only Number tags can be referenced. Verify the tag type in the properties panel.
Formula result is NaN or unexpected
- Check for a division by zero — if a referenced tag has a value of
0and it appears in a divisor position, the result is undefined. - Verify the expression uses
*for multiplication, notxor×.
Circular reference
A formula cannot reference another formula tag, and two formula tags cannot reference each other in a way that creates a loop. If you need a value derived from another formula, use a hidden formula tag as an intermediate step and reference it from there only if the hidden tag is not itself a formula.
Note: The formula evaluator does not support circular references. If a circular dependency is detected, the affected formula will show its fallback value.
Formula does not calculate in the editor preview
This is expected. Formula tags display the expression text in the template editor preview. The formula evaluates only during live signing when recipients are actively filling in tags.
To verify the formula calculates correctly, send a test agreement to yourself and fill in the referenced tags.
Validation rules
The following expression problems are caught immediately when you save the formula:
| Issue | Error message |
|---|---|
| Unclosed bracket | Unclosed field reference: missing ] |
| Empty bracket | Empty field reference: [] |
| Two field references with no operator | Missing operator between field references |
| Unbalanced parentheses | Unbalanced parentheses: missing ) |
Fix any validation errors before saving the template — invalid formulas cannot be used in agreements.
Related articles
- Tag Types — overview of all 15 tag types including Formula
- Tag Properties — configure labels, read-only, and other shared properties
- Conditional Tags — show or hide tags based on recipient selections