PandaDoc 'merge field not found' - the field exists in the template but the API name differs

TL;DR

PandaDoc's 'merge field not found' almost never means the field is missing - it means the API name you sent does not match the token text in the template. The editor shows a display label; the API matches on the exact token string, and a case difference, a trailing space, or a renamed field breaks the match. Open the template editor, copy the field's token text exactly, and use that string verbatim in your API payload. When in doubt, list the template's fields via the API and diff against what your code sends.

The query

PandaDoc 'merge field not found'  -  the field exists in the template but the API name differs

Use this when

• PandaDoc returns merge field not found but you can see the field in the template editor
• The integration worked until someone edited the template
• Fields with similar names (Company, Company Name) collide or mismatch

Not for

• Fields that render blank in the sent document - those were found but had no value
• Template-not-found errors, which are about the template itself, not its fields
• Pricing-table merge problems, which follow the pricing-table field rules

Steps

1. Copy the exact token text from the editor

Open the template in the PandaDoc editor, click the field, and copy the token text exactly as shown - including capitalization and any spaces. This string is the API name. Paste it into your code rather than retyping it; retyping is how trailing spaces sneak in. Expected output: the literal token string, e.g. a value you can paste into a diff.

2. Diff the token against what your code sends

Print the field names your payload actually contains and compare them to the editor's tokens side by side. Check case, spaces, and punctuation - and check that the field was not renamed in the editor after your code was written.

sent = set(payload["fields"].keys())
print("sent:", sorted(sent))
# compare against the tokens copied from the editor in step 1

Expected output: the two sets match exactly, or the diff names the mismatched field.

3. List the template's fields via the API as ground truth

Fetch the template details from the API and read its field list. This is the authoritative set of names the merge will accept - if your field is not in this list under the name you sent, the editor token and the API name have diverged and the API list wins. Expected output: a field list from the API that either contains your exact name or reveals the real one.

4. Pin the template version your code targets

If editors keep tweaking the template, field names will keep drifting. Either lock the integration to a template version whose fields you have verified, or add a startup check that lists fields and fails fast with the diff when a name changes - a loud failure beats a silently unmerged contract. Expected output: the next template edit that renames a field breaks your check immediately, not a customer's document.

Tool compatibility

PandaDoc API (template and document endpoints). The token-matching behavior is the same across API versions; the editor is the source of the display tokens.

Variant phrasings

• PandaDoc merge field not found field exists in template
• PandaDoc API field name differs from template token
• PandaDoc merge field token vs API name mismatch
• PandaDoc document creation merge field not found renamed field

Why it happens

PandaDoc templates have two names for everything: the human-readable label in the editor and the token string the API matches on. They usually look identical, which is why the error is confusing - but they are compared as exact strings, and any edit that changes the token (a rename, an extra space, a case fix) breaks integrations that hardcoded the old string. The API cannot guess which field you meant, so it fails loudly.

Edge cases / pitfalls

• Duplicated field names across sections can make the API match a different field than the one you see in the editor.
• Copy-pasting templates carries the old tokens; verify fields on the new template, not the source.
• Custom field types (date, dropdown) have the same exact-match rule - the type does not relax the naming.
• Deleting and recreating a field with the same label can produce a different internal token; re-verify after any delete/recreate.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Aty8DPmVNj7sCAmXp6wfTA