PandaDoc Merge Variables Not Populating? Complete Diagnostic Checklist

You are mid-send, the document just generated, and half the tokens are blank or showing as literal [Deal.name]. Fixable in under ten minutes once you identify which of nine root causes applies. Work the checklist in order; it is sequenced by frequency and the fix is usually in the first three steps.

Quick Fix Checklist

Try these first before diving into the diagnostic flow. One of them clears roughly 70% of cases:

• Confirm the token was inserted from the Token picker, not typed in. Typed text is not a merge tag, it is plain text that looks like one
• Check the token namespace: [Deal.X] needs deal data, [Contact.X] needs an associated contact, [Company.X] needs an associated company
• Open the source deal in HubSpot or Salesforce and confirm the underlying property actually has a value
• Confirm the deal has an associated contact and company. A deal with no associations blanks every Contact and Company token
• Regenerate the document from the CRM sidebar, not from PandaDoc’s Documents tab. Documents created from the wrong entry point lose their CRM context
• If nothing else works, disconnect and reconnect the CRM integration in Settings > Integrations. Stale OAuth is a silent failure

If the answer is not in that list, work the diagnostic flow.

Why Are My PandaDoc Merge Variables Not Populating?

Merge variables fail to populate for one of nine reasons, in order of frequency: wrong token namespace, unassociated CRM records, custom property not exposed to the integration, plan-tier gating on custom-object fields, tokens that were typed rather than inserted, document created from the wrong CRM object, formatting mismatches, blank source data, or expired integration OAuth.

Each of those has a distinct visual signature in the generated document, which is how you tell them apart.

How Do I Tell If a Token Is Broken vs Just Empty?

Two very different failures look similar at a glance. The distinction saves hours:

Literal [Deal.dealname] text in the document. The token is not recognised at all. It was typed manually, has a typo, or the integration cannot reach that object.

Blank space (surrounding text collapses). The token resolves, but the source field is empty or the associated record does not exist. Data problem, not template problem.

Wrong value (e.g., another deal’s name). The document was created from the wrong CRM record.

Open the generated document beside the source CRM record. That comparison alone tells you which cause applies.

What Is the Correct Token Namespace for Each Field?

PandaDoc tokens live inside named namespaces that correspond to CRM object types. Using [Contact.firstname] on a deal with no associated contact returns blank, even if the contact exists elsewhere in your CRM.

Reference table for the most common tokens across HubSpot and Salesforce:

Field	HubSpot Token	Salesforce Token	Source Object
Deal / Opportunity name	[Deal.dealname]	[Opportunity.Name]	Deal / Opportunity
Deal value	[Deal.amount]	[Opportunity.Amount]	Deal / Opportunity
Expected close date	[Deal.closedate]	[Opportunity.CloseDate]	Deal / Opportunity
Contact first name	[Contact.firstname]	[Contact.FirstName]	Associated contact
Contact last name	[Contact.lastname]	[Contact.LastName]	Associated contact
Contact email	[Contact.email]	[Contact.Email]	Associated contact
Company / Account name	[Company.name]	[Account.Name]	Associated company / account
Company website	[Company.domain]	[Account.Website]	Associated company / account
Deal / Opportunity owner name	[HubSpot_Owner.name]	[Opportunity.Owner.Name]	Owner user record
Deal / Opportunity owner email	[HubSpot_Owner.email]	[Opportunity.Owner.Email]	Owner user record
Custom deal property	[Deal.your_property_internal_name]	[Opportunity.Your_Custom_Field__c]	Deal / Opportunity
Custom contact property	[Contact.your_property_internal_name]	[Contact.Your_Custom_Field__c]	Associated contact

Two things about this table:

HubSpot uses lowercase internal names with underscores. The display label is not the token name. Find the internal name at HubSpot Settings > Data Management > Properties, click the property, copy the “Internal name” field.

Salesforce custom fields end in __c. Standard fields do not. A custom field called “Contract Length” becomes [Opportunity.Contract_Length__c], not [Opportunity.contract_length].

How Do I Check If a Token Is a Real Merge Tag or Plain Text?

Real merge tags render as a coloured pill in the PandaDoc template editor when you click on them. Plain text that happens to look like a token (e.g., someone typed [Deal.name] by hand) renders as regular black text with no interactive behaviour. Click each token in the template to verify.

Fix: delete the plain text, put your cursor in place, use Insert > Token and pick the field. Never type brackets or property names by hand.

This trap catches every team that migrates a Word or Google Docs template into PandaDoc by copy and paste. The bracket text comes across as characters, not tokens, and looks correct in the editor until the document generates.

Why Is the Deal Populating but the Contact and Company Are Blank?

The deal has no associated contact and company records in your CRM. [Deal.X] tokens pull directly from the deal, so they work. [Contact.X] and [Company.X] tokens pull from records associated with that deal, and if no association exists, they resolve to blank.

Fix in HubSpot: open the deal, scroll to Associations on the right sidebar, confirm both Contacts and Companies have at least one record. Associate the correct records and regenerate.

Fix in Salesforce: on the Opportunity, confirm the Account field is populated and at least one Contact Role exists (the primary is what PandaDoc reads). Regenerate.

Common pattern: sales ops imports deals from a spreadsheet without setting associations. Every document blanks Contact and Company tokens. No amount of template editing fixes it. It is a CRM data problem.

Why Is My Custom Property Not Showing in the Token Picker?

Custom properties do not appear in PandaDoc’s token picker unless the CRM integration has permission to read them. On HubSpot, custom deal properties usually surface automatically but custom object properties do not. On Salesforce, custom fields appear only if the connected user’s profile has field-level read access.

For HubSpot custom deal properties that do not appear: go to PandaDoc Settings > Integrations > HubSpot, click Manage, and use the “Refresh fields” button. This forces PandaDoc to re-fetch the property list. New HubSpot properties often do not appear until this runs.

For Salesforce custom fields that do not appear: the integration user needs Field-Level Security read access. Go to Salesforce Setup > Object Manager > (your object) > Fields & Relationships, click the field, click Set Field-Level Security, confirm the PandaDoc integration profile has Visible checked. Reconnect the integration in PandaDoc.

Are Custom-Object Fields Blocked by My Plan?

Custom-object token support is a plan-gated feature. If you are trying to pull data from HubSpot custom objects or Salesforce custom objects other than the standard Opportunity / Account / Contact, you need PandaDoc Enterprise. On lower tiers, those tokens either do not appear in the picker or render blank.

Standard HubSpot deal, contact, and company tokens work on PandaDoc Business. HubSpot custom objects need Enterprise. Same on Salesforce: standard Opportunity, Account, Contact work on Business, custom objects need Enterprise.

If upgrading is not on the table, mirror the custom-object field onto a standard object property using a CRM workflow. PandaDoc can then read it as a standard token.

Was the Document Created from the Correct CRM Object?

PandaDoc binds a document to exactly one CRM record at creation time. If a document was created from a HubSpot contact but the template uses [Deal.X] tokens, every deal token resolves to blank because there is no deal in scope.

The fix is entry-point discipline. Always create the document from the CRM sidebar of the object type your template targets:

• Templates using [Deal.X] or [Opportunity.X] tokens: create from the deal / opportunity record
• Templates using only [Contact.X] tokens: create from the contact record (rare for proposals)
• Templates using only [Company.X] or [Account.X] tokens: create from the company / account record (rarer still)

If the document was created from PandaDoc’s Documents tab rather than the CRM sidebar, no CRM record is bound and every merge tag will be blank. Delete and recreate from the correct CRM record.

Standardise the entry point at the sales-process level. If reps sometimes start from a deal and sometimes from a contact, half your documents will have missing fields. Setup guidance for the PandaDoc HubSpot integration and Salesforce integration cover this.

Why Does the Value Populate but Look Wrong?

The token is resolving correctly but the format is off. Currencies show as 1500 instead of $1,500.00. Dates show as 1712880000 (Unix timestamp) instead of 04/12/2026. Names show in lowercase. These are formatting mismatches, not data problems.

Fix in the template, not in the CRM. In the PandaDoc template editor, click the token pill, and a formatting panel opens. Set:

• Currency tokens: currency symbol, decimal places, thousands separator
• Date tokens: date format (MM/DD/YYYY, DD/MM/YYYY, “Month DD, YYYY”)
• Number tokens: decimal places, rounding behaviour
• Text tokens: case (Title Case, UPPERCASE, lowercase)

CRM data comes through raw. Formatting is a template concern. Do not fix currency display by changing HubSpot’s default currency settings, that breaks reporting without fixing the document.

Is the Source Property Actually Populated in the CRM?

Half the time the token, the namespace, and the associations are all correct. The source field is just empty on the specific record. PandaDoc cannot invent data.

Open the CRM record and look at the field the token references. If blank there, blank in the document. This is where template defaults earn their keep.

Set a fallback: click the token in the template editor and set a Default value in the token panel. If the CRM field is blank, PandaDoc renders the default. Useful for optional fields like billing addresses, secondary contact names, or PO numbers.

If proposals are blanking a critical field because reps do not fill it before generating, add a required-field rule in the CRM or a validation that blocks the deal from moving past a stage without it.

Did the Integration OAuth Expire?

HubSpot and Salesforce OAuth tokens expire, sometimes without a visible warning in PandaDoc. When that happens, the connection appears live in the Integrations panel but no data flows. Every merge tag renders blank or literal, and no error message tells you why.

To force a reconnect:

1. Go to PandaDoc Settings > Integrations
2. Find HubSpot or Salesforce and click Disconnect
3. Wait 30 seconds, then click Connect again
4. Sign in with an admin account (not a standard user) when the OAuth flow prompts
5. Regenerate a test document from the CRM sidebar

If SSO is enforced on the CRM, reconnect from an account that completes the SSO handshake. Service accounts that bypass SSO sometimes create broken connections that look live but resolve nothing.

Same fix applies if the person who installed the integration left and their user was deactivated. The OAuth token was bound to that user. Reconnect from a current admin.

How Do I Test a Template Without Sending It?

Create a test document from a known good CRM record and open it before sending. In PandaDoc, click Preview in the top-right of the document editor to see exactly how each token resolves, without triggering send.

Preview shows resolved values inline. Blank in Preview means blank in the sent document. The template editor view shows token names, not resolved values, so it will not catch this.

Keep one fully populated test deal (with associated contact and company) as the source for every template test. If a token blanks against the test deal, the template is broken. If it blanks against a real deal only, the source data is empty. See the template hardening process if you inherited a template library.

When to Stop Debugging and Get Help

If you have worked every step above and tokens still do not populate, the situation is usually one of these:

• Multi-portal HubSpot setup with the wrong portal connected
• Salesforce sandbox connected instead of production (or vice versa)
• Custom object with a non-standard association topology
• CPQ or billing tool sitting between PandaDoc and the CRM
• Template migrated from an older PandaDoc account with legacy token formats

These benefit from a live look. If you need this resolved before your next send, book a PandaDoc troubleshooting session. We work directly in your account and CRM and hand it back working.

FAQ

Why does my token show as literal [Deal.dealname] in the sent document?

The token was typed as plain text rather than inserted from the token picker. Delete the text, place your cursor, and use Insert > Token in the PandaDoc template editor. Real tokens render as coloured pills when clicked, plain text does not.

Why is my Contact token blank when the deal token works?

The deal has no associated contact record. [Contact.X] tokens pull from the contact associated with the deal, not from contacts anywhere in the CRM. Open the deal in HubSpot or Salesforce and add a contact association, then regenerate.

How do I find the correct internal name of a HubSpot custom property?

Go to HubSpot Settings > Data Management > Properties, search for the property, click it, and copy the “Internal name” field. That exact string (lowercase, underscores) goes inside the token: [Deal.internal_name_here].

Do custom object tokens work on PandaDoc Business tier?

Standard object tokens (Deal, Contact, Company, Opportunity, Account) work on Business. HubSpot custom objects and Salesforce custom objects other than the standard three require PandaDoc Enterprise. Mirror the field onto a standard object as a workaround.

Why did tokens work yesterday and stop working today with no changes?

Almost always expired OAuth on the CRM integration. Go to PandaDoc Settings > Integrations, disconnect the CRM, wait 30 seconds, and reconnect from an admin account. If SSO is enforced on the CRM, reconnect from an account that completes the SSO flow rather than a bypass account.