Salesforce Merge Fields: A Beginner’s Guide With Examples (2026)
Salesforce merge fields are the engine behind every automated document your CRM can produce. They are the placeholders that tell a document template where to pull live data from a Salesforce record. When a document generates, every merge field gets replaced with the real value from that specific record at that specific moment.
If you have opened a contract template and seen something like {{Account.Name}} or {{Opportunity.Amount}} inside curly braces, those are merge fields. They look technical but the concept is straightforward: reference an object, reference a field on that object, and the value appears in your document automatically.
This guide covers everything a beginner needs to know about Salesforce merge fields, from basic syntax to related record traversal, conditional logic, and formatting. For the broader context, see our guide on what Salesforce document generation is.
What are Salesforce merge fields?
Salesforce merge fields are dynamic placeholders in a document template that reference specific field values on a Salesforce record. When a document is generated from that record, the template engine reads each merge field, looks up the corresponding value in Salesforce, and inserts it into the finished document.
The result is a document that is automatically personalised to the record it came from, with zero manual data entry. The same template generates a different document for every record because the merge fields pull from the live data in your Salesforce org.
Salesforce uses merge fields across several parts of the platform: email templates, formula fields, and Visualforce pages. In document generation, they are the core mechanism that makes automated contracts, invoices, NDAs, and offer letters possible.
Understanding Salesforce merge field syntax
The syntax for Salesforce merge fields follows a consistent structure: the object name and the field API name, separated by a dot, wrapped in double curly braces.
{{ObjectName.FieldAPIName}}
{{Account.Name}} — account or company name
{{Opportunity.Amount}} — deal value
{{Contact.Email}} — primary contact email
{{Contract.StartDate}} — contract start date
{{Lead.Company}} — company name from a Lead
{{Case.CaseNumber}} — auto-generated case number
The field API name and the field label are not always the same. A field labelled “Annual Revenue” has an API name of AnnualRevenue with no space. Always use the API name in your merge fields, not the label.
Custom fields created by your Salesforce admin always end in __c. A custom field labelled “Contract Reference” would have an API name like Contract_Reference__c.
To find a field’s API name: go to Setup, open Object Manager, select the relevant object, click Fields and Relationships, and check the Field API Name column.
Read more: How to Generate Documents in Salesforce: Step-by-Step Guide (2026)
Common merge field examples by document type
The merge fields you need depend on which Salesforce object your document is generated from. Here are the most common document types and the fields typically used in each.
Common merge fields by document type — each references the field API name of the corresponding Salesforce object.
| Document | Merge field | Pulls from |
|---|---|---|
| Contract | {{Account.Name}} | Client company name |
| Contract | {{Opportunity.Amount}} | Total contract value |
| Contract | {{Contract.StartDate}} | Agreement start date |
| Invoice | {{Opportunity.CloseDate}} | Invoice date |
| Invoice | {{Owner.Email}} | Account manager email |
| Offer Letter | {{Contact.FirstName}} | Candidate first name |
| Offer Letter | {{Job_Application__c.Job_Title__c}} | Role being offered (custom) |
| NDA | {{Contact.Name}} | Counterparty full name |
Pulling data from related records in Salesforce
The most powerful use of Salesforce merge fields in document generation is traversing relationships to pull data from related records. A document generated from an Opportunity may also need data from the related Account, the Contact, the owner’s profile, or a custom related object.
Related record traversal works by chaining the relationship name with the field name using dot notation extended to multiple levels.
{{Opportunity.Account.BillingCity}} — billing city from Account related to Opportunity
{{Contact.Account.Name}} — account name from Account related to Contact
{{Opportunity.Owner.Email}} — email of the Opportunity owner (User)
{{Case.Contact.Phone}} — phone of the Contact related to the Case
{{Opportunity.Primary_Contact__r.Email}} — custom lookup field using __r
{{Account.Account_Manager__r.Name}} — custom Account Manager lookup
The __r suffix signals to the document generation tool that you are traversing a custom relationship rather than reading a field value directly. Standard relationships like Account, Owner, and Contact do not use __r because they are predefined.
Relationship traversal lets a single document template pull data from multiple related Salesforce objects.
Repeating sections and line items in document templates
Most real-world documents need a repeating section for line items: a contract with multiple deliverables, an invoice with multiple products, a proposal with multiple pricing tiers. A repeat block is a section of the template that the document generation tool iterates through once for each related child record.
Start repeat for each OpportunityLineItem
Product: {{OpportunityLineItem.Name}}
Quantity: {{OpportunityLineItem.Quantity}}
Unit Price: {{OpportunityLineItem.UnitPrice}}
Total: {{OpportunityLineItem.TotalPrice}}
End repeat
The tool runs through every related line item and generates one table row for each one. Three products produce three rows. Twelve products produce twelve rows. The template does not change.
Test your repeat blocks with a record that has zero child records. If the repeat block is not configured to handle an empty related list gracefully, the section will error or leave blank space in the output.
Empty list handling: Always configure a default empty-state for repeat blocks. Without it, a record with zero child records can break the document layout or produce a blank section with no explanation.
Conditional merge fields: show or hide content by record value
Conditional logic in document templates allows sections to appear or disappear based on the value of a Salesforce field on the record being generated. A contract that includes different payment terms for enterprise versus standard customers. An offer letter that adds a relocation clause only for candidates outside the city.
If Opportunity.RecordType.Name equals Enterprise:
This agreement is subject to enterprise service terms.
End if
If Contact.MailingCountry equals United Kingdom:
This agreement is governed by the laws of England and Wales.
Otherwise:
This agreement is governed by the laws of the State of New York.
End if
Build conditional blocks around record type, industry, region, contract value tier, and custom boolean fields that flag specific requirements.
Date and number formatting in Salesforce merge fields
Raw Salesforce field values often need formatting before they are readable in a finished document. Dates come through in ISO format by default. Currency values may appear as plain numbers. Most document generation tools support format modifiers applied directly in the merge field.
{{Contract.StartDate | date: "MMMM D, YYYY"}} — outputs July 15, 2026
{{Opportunity.CloseDate | date: "D MMM YYYY"}} — outputs 15 Jul 2026
{{Opportunity.Amount | currency}} — outputs $125,000.00
{{Invoice__c.Total__c | currency: "GBP"}} — outputs £125,000.00
{{OpportunityLineItem.Quantity | number: "0,0"}} — outputs 1,200
Handling blank fields in Salesforce merge fields
A merge field that references a field with no value on the record produces either a blank space or the raw field token in the output. The best practice is to set default values for any field that may legitimately be empty on some records.
{{Contact.MiddleName | default: ""}} — outputs nothing if blank
{{Opportunity.Description | default: "See attached scope of work"}}
{{Account.BillingCountry | default: "United Kingdom"}}
Review every merge field in your template before going live and add a default value for any field that is optional or may be blank on some records.
How Salesforce merge fields work in Dochly
Dochly is a 100% native Salesforce document generation app, which means merge fields in Dochly templates read directly from your Salesforce org without any data leaving the platform.
The template editor supports standard merge field syntax, related record traversal using the __r notation, repeat blocks for child object line items, conditional sections, and all standard format modifiers for dates and currency.
Because Dochly runs natively inside Salesforce, merge field resolution happens inside your org’s security boundary. Field-level security applies automatically: if a running user does not have permission to see a field, the merge field for that field resolves to blank rather than exposing restricted data. You do not need to configure this separately.
Dochly resolves merge fields natively inside your Salesforce org — field-level security and sharing rules apply automatically with no extra configuration.
Frequently asked questions about Salesforce merge fields
Salesforce merge fields are the foundation of every automated document your team will generate. Understanding the syntax, related record traversal, and conditional logic covered in this guide is all you need to build templates that work reliably across thousands of records.
For the next step, see our guide on how to generate documents in Salesforce step by step, or visit Dochly document generation to see merge fields in action inside a fully native Salesforce app.