Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spitshake.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

  1. Add a formula property to any number or payment field in the template schema.
  2. Reference other fields by name using {Field Name} syntax.
  3. DocuTrust evaluates the formula in real time as the signer fills in referenced fields.
  4. 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

OperatorDescriptionPrecedenceExample
( )GroupingHighest({Price} + {Tax}) * {Quantity}
*MultiplicationHigh{Quantity} * {Unit Price}
/DivisionHigh{Total} / {Installments}
+AdditionLow{Subtotal} + {Shipping}
-SubtractionLow{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:
FieldFormulaComputed Value
Subtotal{Quantity} * {Unit Price}250
Tax (8.75%){Subtotal} * 0.087521.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.