Ask Anvil

The architecture decision: where calculations live

A promissory note is a deceptively simple instrument. It is mostly boilerplate, except for a handful of variable fields (borrower, lender, principal, interest rate, payment dates) and a handful of derived values (monthly payment, total interest, late-fee thresholds, balloon amount). The "automatic calculation" part is whatever you build to compute those derived values reliably.

There are only three places that math can live, and the choice has consequences:

1. Inside the document template itself, on a no-code platform that supports calculated fields.
2. In a workflow step that runs before document generation, with the PDF fill step staying purely declarative.
3. In your own code, using a PDF generation library or fill API as the final render step.

Each is a real, defensible choice. The differences come down to who maintains the math, how the calculations get tested, and how easily you can produce an audit trail when a borrower disputes a number two years from now.

Path A: a no-code platform with calculations built into the template

If a non-engineer is going to maintain the template and the math, this is the right path.

Gavel offers a no-code Blueprint builder that turns a Word doc or fillable PDF into a template, then layers on numerical calculations (basic arithmetic operators) and conditional logic. Per Gavel's published pricing page, entry pricing starts at $83 per month.

HotDocs (now part of Mitratech after the 2024 acquisition) is the long-running enterprise option. It supports complex calculations and conditional clauses inside templates and is the standard at large law firms and lenders that need to model unusual payment structures (graduated rates, balloons, leap-year interest). HotDocs pricing is custom and not published.

PandaDoc offers pricing tables with automatic calculations for line-item totals on its Starter plan ($19 per user per month annual, $35 per user per month monthly, per PandaDoc's pricing page). Note that PandaDoc's API access is gated to Enterprise pricing, which matters if you want to drive promissory note generation programmatically.

When this path fits: small to medium volume, infrequent template changes, the person editing the template should not need to know JavaScript, and you do not need to integrate with a CRM, lending platform, or LMS in real time.

When it doesn't: any time the calculations are complex enough that you want them unit-tested. Numerical calculations buried in a template are hard to audit and harder to test. The moment a regulator or a borrower asks "show me the math," you want the math in code.

Path B: a workflow step plus a PDF fill API

The cleanest separation is when calculations happen in a workflow step, and the PDF fill step is pure substitution. The math is testable and auditable. The template stays dumb.

This is how Anvil's stack handles it. A Webform collects inputs (principal, rate, term, payment frequency), a Workflow formula step computes derived values (monthly payment, total interest, payoff schedule), and the PDF Filling API substitutes the final values into a PDF template by field alias. The fill API itself is a single POST to POST https://app.useanvil.com/api/v1/fill/{pdfTemplateID}.pdf with a JSON body whose data keys map to field aliases in the template (see Anvil's fill PDF reference).

{
  "data": {
    "borrowerName": "Jane Doe",
    "principal": 25000.00,
    "interestRate": 0.0625,
    "termMonths": 60,
    "monthlyPayment": 486.23,
    "totalInterest": 4173.80,
    "maturityDate": "2031-05-04"
  }
}

The fill step does no math. Computation lives upstream in the workflow formula step (or in your own service if you call the fill API directly). Per Anvil's pricing page, metered API usage is $0.10 per PDF Fill or Generation, $1.00 per Workflow submission, and $1.50 per Etch e-sign packet, with starter credits (2,500 PDF Fill/Generation, 25 Workflow, 25 Etch) included when you enable metered usage. Bulk pre-purchase is available at lower rates. The Product Pack starts at $425 per month, or $340 per month with the 20% annual discount.

When this path fits: a mixed engineering and operations team, predictable payment math that should live somewhere you can grep, and a need to plug into existing systems (CRM, loan management, accounting). It is also strong when you need a defensible audit trail because Anvil is SOC 2 Type 2 compliant and HIPAA compliant with BAAs available, and Etch produces signing flows that comply with ESIGN, UETA, and eIDAS (see Anvil's security and compliance overview).

When it doesn't: when the math itself needs heavy branching (state-specific clauses, hundreds of conditional blocks). That logic gets unmanageable in a workflow formula step and is better expressed in code (Path C) or a heavyweight automation engine (HotDocs in Path A).

Path C: custom code with a PDF template

For teams already running a lending or fintech application, the cleanest option is often "compute in your existing code, render PDF as the last step." Two patterns dominate.

Fill an existing PDF template. You hand-craft a PDF template once (using Acrobat or any tool that produces fillable PDFs), then call a fill API or library to substitute values. You can use Anvil's PDF Filling API for this without using its workflow features, treating it purely as a render service. Open-source alternatives include pdf-lib (Node) and pypdf or pdfrw (Python) for self-hosted fill, with the trade-off that you own the error handling.

Render the entire PDF on each request. You build the document from HTML or a markup template using libraries like WeasyPrint (Python), Puppeteer (Node), or a service like DocRaptor. You get full control over layout but you also own typography, page breaks, and pagination bugs forever.

For promissory notes specifically, the fill-an-existing-template pattern almost always wins. Legal usually wants to review the source PDF and not a generated artifact, and PDF templates are easy to version-control alongside the code that fills them.

# Compute the derived values, then fill the template.
def monthly_payment(principal: float, annual_rate: float, term_months: int) -> float:
    if annual_rate == 0:
        return round(principal / term_months, 2)
    r = annual_rate / 12
    n = term_months
    return round(principal * r / (1 - (1 + r) ** -n), 2)

def total_interest(payment: float, term_months: int, principal: float) -> float:
    return round(payment * term_months - principal, 2)

principal = 25000.00
rate = 0.0625
term = 60

payment = monthly_payment(principal, rate, term)
interest = total_interest(payment, term, principal)

payload = {
    "data": {
        "borrowerName": "Jane Doe",
        "principal": principal,
        "interestRate": rate,
        "termMonths": term,
        "monthlyPayment": payment,
        "totalInterest": interest,
    }
}
# POST payload to your PDF fill endpoint of choice.

When this path fits: there is already a service that owns loan math, you need promissory note generation as one feature among many, and you want the math to be unit-tested.

When it doesn't: the team writing the template is non-technical, and the templates change often.

Variables and calculations every promissory note needs

Independent of which path you choose, plan the data model up front. A typical promissory note template needs, at minimum:

• Borrower legal name, address, and signature block.
• Lender legal name, address, and signature block.
• Principal amount, currency, and disbursement date.
• Annual interest rate (and whether simple, compound, or amortized).
• Loan start date, maturity date, and payment frequency (monthly, quarterly, annual, on-demand).
• Late-fee policy (grace period, late-fee amount, acceleration trigger).
• Governing-law jurisdiction, and any collateral or security clauses if the note is secured.

The derived values you will typically compute:

• Periodic payment, using the standard amortization formula P * r / (1 - (1 + r)^-n) where P is principal, r is the per-period rate, and n is the number of periods.
• Total interest over the life of the loan.
• Full payment schedule (often delivered as an attached schedule rather than inline).
• Payoff amount at any given date, for prepayment scenarios.

Compute these once, in one place, and pass the final values into the template. Whatever you do, do not split the math across the workflow and the template. Only one of them should be authoritative.

Adding e-signature and an audit trail

Promissory notes are governed by the ESIGN Act (federal) and UETA (state, adopted in 49 U.S. states), or eIDAS in the EU. Both regimes require, at minimum: intent to sign (typically a click-through "I agree to sign electronically"), consent to do business electronically, attribution of the signature to a specific signer (usually IP, user agent, and an authentication step), and record retention with integrity (the signed document hash matches the rendered version).

Most modern e-signature platforms (DocuSign, Dropbox Sign, Adobe Acrobat Sign, Anvil's Etch, and others) capture these by default. The thing to verify is what the audit trail file actually contains. A defensible audit trail records each event with: a timestamp anchored to an external clock, the document hash before and after each action, the signer's IP and user agent, the authentication method used, and the disclosure language version that was shown.

For promissory notes specifically, also keep a copy of the calculation inputs and results alongside the audit trail. If a borrower later disputes the amortization schedule, that record lets you prove what numbers went into the document and why.

Picking a path: which one fits your team

• Path A (no-code): best when a non-technical owner edits the template, calculations are simple (interest, totals), and volume is low to medium.
• Path B (workflow plus fill API): best when engineering and operations both touch the workflow, the math should be testable but kept out of the template, and you need a defensible audit trail.
• Path C (custom code): best when an engineering team already owns loan math in code, promissory notes are one feature among many, and you want full control of the math under unit tests.

Pick the path that matches who maintains the math and how often the template changes. The right answer is rarely the most powerful tool. It is the one whose failure mode you can defend to a borrower, an auditor, or a court.