--- title: "PandaDoc Variables and Merge Fields: The Complete Setup Guide" description: "How PandaDoc variables work: the five variable types, naming rules, CRM field mapping, variables in titles and pricing tables, and how to design a template that fills itself in." canonical: https://pureproposals.com/pandadoc-variables-merge-fields-guide/ published: 2026-10-12 image: https://pureproposals.com/images/blog/pandadoc-variables-merge-fields-guide/0.png site: Pure Proposals type: article --- # PandaDoc Variables and Merge Fields: The Complete Setup Guide > How PandaDoc variables work: the five variable types, naming rules, CRM field mapping, variables in titles and pricing tables, and how to design a template that fills itself in. _Source of truth: https://pureproposals.com/pandadoc-variables-merge-fields-guide/_ PandaDoc variables are merge fields, written as text in square brackets like `[Client.FirstName]`, that auto-fill recurring details into a proposal so nobody types the client's name, the price, or the date by hand. There are five kinds: custom variables you fill at creation, role variables filled from the assigned recipient, system variables filled from document data, pricing table variables filled from the table's own totals, and CRM-fed variables filled from the deal or opportunity the document was created from. Set up well, variables are the difference between a template that saves formatting and a template that saves the whole job. Manual proposal creation was the top pain in 82 of the 129 sales calls we analysed, and the teams stuck at 45 to 50 minutes per proposal are almost always retyping information their CRM already holds. This guide covers how each variable type works, the naming rules that keep them from breaking, and how to design a template where the only thing a rep edits is the thing that is genuinely new about the deal. ## Key takeaways - A variable is text in square brackets. In the editor it carries a yellow highlight; the recipient never sees the highlight, only the filled value. Variables are available on every PandaDoc plan tier, including Starter. - The five types fill from different sources: custom (typed once at creation), role (the assigned recipient's contact details), system (document data like sent date and reference number), pricing table (footer rows of a table), and CRM-fed (fields on the deal, contact, or company the document was created from). - Fill a variable once and it updates everywhere it appears, which is why a proposal should reference the client's name through one variable rather than fifteen hand-typed mentions. - Variables work in the document body, in titles, and in three pricing table fields (Name, Description, and plain text columns). They do not work in saved messages or in the email subject and body. - CRM-fed variables only populate from fields your team reliably fills in. Map the variable to the field that always has a value, not the field that should have one. - Insert variables from the picker or the panel; a token typed by hand with a typo is plain text that looks like a variable and fills with nothing. ## What a variable is and where it works A PandaDoc variable is a placeholder that connects a spot in the document to a single source of truth. Type `[` in any text block and the variable picker opens: choose an existing variable or type a new name and press Enter to create a custom one. The Variables panel on the right side of the editor lists everything in the document, lets you add new custom variables, and lets you fill values in one place rather than hunting through pages. Where they work, verified against PandaDoc's current documentation: - **Document and template body.** Any text block, anywhere. - **Titles.** Variables in a template title carry into the document title, and CRM variables in a title fill from the deal's field values. Three exceptions: titles in forms, in the documents inside a bundle, and in bulk send do not support variables. - **Pricing tables.** The Name, Description, and plain text column fields accept variables; calculated columns do not. Where they do not work: saved messages and the email subject and body. If the send email needs the client's name, that is the recipient's contact record doing the work, not a variable. One behaviour drives the whole design approach: filling a variable fills every instance of it at once. A proposal that mentions the client company fifteen times should contain one `[Company.Name]` variable fifteen times, not fifteen typed company names. That is also why deleting a variable requires removing every instance from the body first; PandaDoc then lists it under Not used in the panel, where it can be deleted. ## The five variable types and what fills each one ### Custom variables: typed once, used everywhere Custom variables are placeholders you name yourself and fill manually when the document is created: `[Project.StartDate]`, `[Scope.Summary]`, `[Payment.Terms]`. They are the right tool for information that lives in nobody's system: the specific go-live date agreed on the call, the one-line scope summary, the custom milestone. The discipline that matters: a custom variable is a prompt for the rep, so name it like one. A document with `[Date1]` and `[Date2]` gets guessed at; a document with `[Project.KickoffDate]` and `[Project.GoLiveDate]` gets filled correctly. Rename an existing custom variable from the three-dot menu in the Variables tab and every instance updates. ### Role variables: the recipient fills them by being assigned Role variables are created at the template level only. Define a role on the template, say Client, and PandaDoc generates `[Client.FirstName]`, `[Client.LastName]`, `[Client.Email]`, `[Client.Company]`, `[Client.Phone]`, `[Client.Title]`, and `[Client.Address]`. When a document is created from the template and a recipient is assigned to the Client role, those variables fill from the recipient's record in PandaDoc Contacts; a recipient who is not in Contacts yet can be added during creation. This is the cheapest personalisation in the product: zero typing, filled at the moment of creation, and impossible to misspell the client's name. Every client-facing template should address the recipient through role variables, never through typed text. ### System variables: the document describes itself System variables are predefined and fill from the document's own data: created date, reference number, document value, and send-dependent values like `[Document.SentDate]` and `[Document.ExpirationDate]`, which stay empty until the document is actually sent. Use them for the quote validity line ("this proposal expires on `[Document.ExpirationDate]`"), reference numbers in footers, and anywhere a date would otherwise be typed and forgotten. Date formatting follows your workspace's default date format, so set that once in settings rather than fighting it per document. ### Pricing table variables: totals that travel Every footer row of a pricing table that carries a value becomes a variable automatically: subtotal, discount, tax, total. Find them by selecting the table, opening the gear icon, then Properties and Variables, or in the Variables tab, and copy the one you need into the body text. That is how "Your total investment is $14,250" in the executive summary stays identical to the table on page four after the third revision. Renaming the table renames its variables automatically, so name tables deliberately. For the table mechanics themselves, our [pricing tables guide](/pandadoc-pricing-tables-complete-guide/) covers quantities, optional items, and discount governance. ### CRM-fed variables: the template reads the deal When a document is created from a deal in HubSpot, an opportunity in Salesforce, or a record in a connected CRM, tokens mapped to CRM fields fill with that record's values: deal name, amount, close date, contact details, company details, plus any custom property the integration exposes. Created from a deal, a template title with CRM variables fills from the deal's fields; without them, PandaDoc swaps the title for the deal or opportunity name. This is where the biggest time win lives, and where discipline matters most, so it gets its own section. ## The reliably-populated rule for CRM variables A CRM-fed variable is only as good as the field behind it, and the rule we apply on every build is simple: map variables to fields your team reliably fills in, not fields that should be filled in. A beautiful template referencing twelve deal properties produces documents with twelve blanks if reps only populate four of them. Audit the CRM before the template: pull the last 20 won deals and check which fields actually carry values on all 20. Those are your variable candidates. Everything else either becomes a required field in the CRM first, or stays a custom variable the rep fills by hand. Two mechanical rules sit alongside it: - **Insert tokens from the picker, never type them.** A typed token with the wrong internal field name is plain text wearing a costume; it fills with nothing and ships to the client as `[Deal.dealname]`. The picker only offers tokens the integration can actually resolve. - **Namespaces follow CRM associations.** A `[Contact.FirstName]` token needs a contact associated to the deal the document was created from; no association, no value. The variable did not break, the deal record is missing its context. When a token that worked yesterday shows blank or literal bracket text today, that is a diagnostic job, not a design job: our [merge variables troubleshooting checklist](/pandadoc-merge-variables-not-populating/) walks the nine root causes in order of frequency. Wired properly, the CRM layer changes the economics of the document. One team we worked with went from around an hour per document to 5 to 10 minutes, and the mechanism was exactly this: the template pulled the deal data, the rep checked it, and nothing was retyped. The [PandaDoc HubSpot integration](/pandadoc-integrations/hubspot/) is the deepest of the native pairings and the one most of our clients run. ## Variables in conditional rules On Enterprise plans, variables do double duty: beyond filling text, they can drive smart content rules that show or hide sections. A `[Deal.Region]` variable can trigger the regional terms block; a product variable can pull in the matching implementation scope. That is the one-template-many-deals pattern, where a single governed template replaces a folder of near-duplicates, and it only works when the variables feeding the rules follow the reliably-populated rule above. The full mechanics, operators, and gating are in our [smart content and conditional logic guide](/pandadoc-smart-content-conditional-logic-guide/). ## Variables are the argument against hand-editing The deeper point is not convenience. Every value a rep types by hand into a proposal is a value that can be mistyped, forgotten in the next revision, or copied stale from the last client's document. Off-brand, inconsistent proposals were the second most common pain in our call data, and a large share of that inconsistency is not fonts or colours, it is hand-edited details drifting between documents: the wrong name carried over from a duplicated file, a price in the summary that no longer matches the table, last quarter's terms date. A properly built template inverts the model: the brand, structure, and standing copy are locked; the deal-specific values arrive through variables; and the rep's editable surface shrinks to the handful of custom variables that are genuinely new per deal. That design argument, lock everything that is not a deal decision, is the spine of our [branded proposal templates guide](/branded-proposal-templates-guide/), and variables are the mechanism that makes it practical. The test we use at handoff: a new hire should be able to produce a correct, on-brand proposal on day one by filling variables alone, without editing a single block of standing text. ## Setting variables up properly A sensible build order for a template's variable layer: 1. **List every value that changes per deal.** Go through a recent real proposal and mark everything that was edited for that specific client. That list is your variable set; anything not on it gets locked. 2. **Assign each value a source.** Recipient details become role variables, CRM fields become CRM-fed tokens (after the reliably-populated audit), document data becomes system variables, totals become pricing table variables, and only the genuine leftovers become custom variables. 3. **Insert from the picker and fill-test immediately.** Create a test document from a fully populated real deal and check every variable resolved before any rep sees the template. 4. **Name custom variables as instructions** and keep the custom set small. If reps face ten manual prompts per document, the template is under-automated; push more of them into the CRM. Variable architecture is one layer of a [PandaDoc template build](/pandadoc-services/pandadoc-templates/), alongside locked branding, the content library, and conditional sections, and the full sequence from scoping to cutover is covered in our [PandaDoc implementation](/pandadoc-implementation/) pillar. If your templates exist but every document still gets hand-edited, the variable layer is usually the missing piece, and it is a build measured in days, not months. ## Frequently asked questions **What is the difference between a variable and a merge field in PandaDoc?** Nothing: they are the same mechanism. PandaDoc's current editor calls them variables; merge field (or merge tag, or token) is the older and more generic term, and CRM users tend to say tokens for the integration-fed kind. All of them are square-bracket placeholders that fill from a data source. **Which PandaDoc plans include variables?** All of them. Custom, role, system, and pricing table variables are available on Starter, Business, and Enterprise. The practical gates sit elsewhere: CRM-fed variables need the relevant integration (most native CRM integrations require Business or above), and smart content rules driven by variables are Enterprise. **Why is my variable showing as blank or as literal bracket text?** Blank means the variable resolved but its source was empty: an unfilled CRM field, a missing associated record, or a custom variable nobody filled. Literal bracket text like `[Deal.dealname]` means the token was never recognised, usually because it was typed by hand with a typo or references a field the integration cannot see. Our [troubleshooting checklist](/pandadoc-merge-variables-not-populating/) sequences the fixes. **Can variables fill the document title and the send email?** Titles yes, including from CRM fields when the document is created from a deal, with three exceptions: forms, documents inside bundles, and bulk send do not support title variables. The send email no: variables do not work in saved messages or in the email subject and body. **How many variables should a template have?** As many as there are genuinely deal-specific values, and no more. A healthy client-facing proposal template typically runs a handful of role variables, a few system and pricing table variables, a set of CRM-fed tokens that passed the reliably-populated audit, and fewer than ten custom variables. If reps are hand-filling more than that per document, move the data upstream into the CRM, or lock copy that should never have been editable.