Formula Fields

Formula fields automatically compute their value from other fields in the template using arithmetic expressions. Use them for totals, taxes, discounts, commissions, and any other calculated values that depend on signer input.

How formulas work

Add a formula property to any number or payment field in the template schema.
Reference other fields by name using {Field Name} syntax.
DocuTrust evaluates the formula in real time as the signer fills in referenced fields.
The computed value updates instantly in the signing form.

Formula syntax

Field references

Reference any field by wrapping its name in curly braces:

{Field Name}

Field references are case-sensitive and must match the field’s name property exactly. If the referenced field is empty or has a non-numeric value, it evaluates to 0.

Supported operators

Operator	Description	Precedence	Example
`(` `)`	Grouping	Highest	`({Price} + {Tax}) * {Quantity}`
`*`	Multiplication	High	`{Quantity} * {Unit Price}`
`/`	Division	High	`{Total} / {Installments}`
`+`	Addition	Low	`{Subtotal} + {Shipping}`
`-`	Subtraction	Low	`{Total} - {Discount}`

Operator precedence follows standard arithmetic rules. Use parentheses to override precedence.

Numeric literals

You can include numeric constants in formulas:

{Subtotal} * 0.0875
{Price} * 1.1
{Base Rate} + 50

Schema example

A complete field with a formula:

{
  "uuid": "f3c4d5e6-f7a8-9012-cdef-123456789012",
  "name": "Subtotal",
  "type": "number",
  "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "required": true,
  "readonly": true,
  "key": "subtotal",
  "default_value": null,
  "placeholder": null,
  "formula": "{Quantity} * {Unit Price}",
  "options": null,
  "areas": [
    {
      "page": 0,
      "x": 0.55,
      "y": 0.40,
      "w": 0.15,
      "h": 0.03,
      "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
    }
  ]
}

Full invoice example

An invoice template with quantity, unit price, subtotal, tax, and grand total fields. The last three are formula fields that compute automatically.

{
  "schema": [
    {
      "uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Quantity",
      "type": "number",
      "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "required": true,
      "readonly": false,
      "key": "quantity",
      "default_value": "1",
      "placeholder": "Enter quantity",
      "formula": null,
      "options": null,
      "areas": [
        {
          "page": 0,
          "x": 0.12,
          "y": 0.40,
          "w": 0.15,
          "h": 0.03,
          "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
        }
      ]
    },
    {
      "uuid": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
      "name": "Unit Price",
      "type": "number",
      "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "required": true,
      "readonly": false,
      "key": "unit_price",
      "default_value": "0",
      "placeholder": "Enter unit price",
      "formula": null,
      "options": null,
      "areas": [
        {
          "page": 0,
          "x": 0.30,
          "y": 0.40,
          "w": 0.15,
          "h": 0.03,
          "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
        }
      ]
    },
    {
      "uuid": "f3c4d5e6-f7a8-9012-cdef-123456789012",
      "name": "Subtotal",
      "type": "number",
      "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "required": true,
      "readonly": true,
      "key": "subtotal",
      "default_value": null,
      "placeholder": null,
      "formula": "{Quantity} * {Unit Price}",
      "options": null,
      "areas": [
        {
          "page": 0,
          "x": 0.55,
          "y": 0.40,
          "w": 0.15,
          "h": 0.03,
          "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
        }
      ]
    },
    {
      "uuid": "f4d5e6f7-a8b9-0123-def0-234567890123",
      "name": "Tax (8.75%)",
      "type": "number",
      "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "required": true,
      "readonly": true,
      "key": "tax",
      "default_value": null,
      "placeholder": null,
      "formula": "{Subtotal} * 0.0875",
      "options": null,
      "areas": [
        {
          "page": 0,
          "x": 0.55,
          "y": 0.45,
          "w": 0.15,
          "h": 0.03,
          "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
        }
      ]
    },
    {
      "uuid": "f5e6f7a8-b9c0-1234-ef01-345678901234",
      "name": "Grand Total",
      "type": "number",
      "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "required": true,
      "readonly": true,
      "key": "grand_total",
      "default_value": null,
      "placeholder": null,
      "formula": "{Subtotal} + {Tax (8.75%)}",
      "options": null,
      "areas": [
        {
          "page": 0,
          "x": 0.55,
          "y": 0.50,
          "w": 0.15,
          "h": 0.03,
          "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
        }
      ]
    }
  ]
}

When the signer enters Quantity = 10 and Unit Price = 25, the computed values update instantly:

Field	Formula	Computed Value
Subtotal	`{Quantity} * {Unit Price}`	`250`
Tax (8.75%)	`{Subtotal} * 0.0875`	`21.88`
Grand Total	`{Subtotal} + {Tax (8.75%)}`	`271.88`

Dynamic payment pricing

Combine formula fields with the payment field type to charge signers a dynamically computed amount based on their input.

{
  "uuid": "p1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "name": "Payment Amount",
  "type": "payment",
  "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "required": true,
  "readonly": false,
  "key": "payment_amount",
  "default_value": null,
  "placeholder": null,
  "formula": "{Grand Total}",
  "options": null,
  "areas": [
    {
      "page": 1,
      "x": 0.12,
      "y": 0.60,
      "w": 0.35,
      "h": 0.06,
      "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
    }
  ]
}

The payment amount updates dynamically as the signer fills in quantity, pricing, and other fields. The signer sees the computed total before confirming payment.

Payment fields require payment configuration to be set up in your account settings. See the Payments feature guide for setup instructions.

Creating formulas via API

Add formula fields when creating or updating a template via PUT /api/templates/:id:

curl -X PUT "$DOCUTRUST_URL/api/templates/42" \
  -H "X-Auth-Token: $DOCUTRUST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": [
      {
        "uuid": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Hours Worked",
        "type": "number",
        "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "required": true,
        "readonly": false,
        "key": "hours_worked",
        "default_value": "0",
        "placeholder": "Enter hours",
        "formula": null,
        "options": null,
        "areas": [
          {
            "page": 0,
            "x": 0.12,
            "y": 0.40,
            "w": 0.15,
            "h": 0.03,
            "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        ]
      },
      {
        "uuid": "f2b3c4d5-e6f7-8901-bcde-f12345678901",
        "name": "Hourly Rate",
        "type": "number",
        "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "required": true,
        "readonly": true,
        "key": "hourly_rate",
        "default_value": "75",
        "placeholder": null,
        "formula": null,
        "options": null,
        "areas": [
          {
            "page": 0,
            "x": 0.30,
            "y": 0.40,
            "w": 0.15,
            "h": 0.03,
            "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        ]
      },
      {
        "uuid": "f3c4d5e6-f7a8-9012-cdef-123456789012",
        "name": "Total Due",
        "type": "number",
        "submitter_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "required": true,
        "readonly": true,
        "key": "total_due",
        "default_value": null,
        "placeholder": null,
        "formula": "{Hours Worked} * {Hourly Rate}",
        "options": null,
        "areas": [
          {
            "page": 0,
            "x": 0.55,
            "y": 0.40,
            "w": 0.15,
            "h": 0.03,
            "attachment_uuid": "d4e5f6a7-b8c9-0123-def0-234567890123"
          }
        ]
      }
    ]
  }'

Safe evaluation

Formula evaluation is sandboxed and safe:

No code execution — only arithmetic expressions are parsed. JavaScript, Ruby, or any other code is rejected.
No external access — formulas cannot access variables, functions, or data outside the template fields.
Division by zero — dividing by zero returns 0 instead of throwing an error.
Non-numeric values — if a referenced field contains a non-numeric value (or is empty), it evaluates to 0.
Circular references — if field A references field B and field B references field A, both evaluate to 0 to prevent infinite loops.
Maximum length — formulas are limited to 500 characters.

Formula fields that reference other formula fields create a dependency chain. DocuTrust evaluates them in dependency order, but circular references are detected and resolved to 0.

Set formula fields to readonly: true so the signer sees the computed value but cannot override it. If you leave readonly: false, the signer can manually change the calculated value.

Getting Started

Core Guides

Embedding

Features

Security & Compliance

Legal

Formula Fields

Formula Fields

How formulas work

Formula syntax

Field references

Supported operators

Numeric literals

Schema example

Full invoice example

Dynamic payment pricing

Creating formulas via API

Safe evaluation

​Formula Fields

​How formulas work

​Formula syntax

​Field references

​Supported operators

​Numeric literals

​Schema example

​Full invoice example

​Dynamic payment pricing

​Creating formulas via API

​Safe evaluation

Formula Fields

How formulas work

Formula syntax

Field references

Supported operators

Numeric literals

Schema example

Full invoice example

Dynamic payment pricing

Creating formulas via API

Safe evaluation