Complete Guide to Document Merge Fields and Variables

What Are Merge Fields?

Merge fields are placeholders in your document template that get replaced with actual data when you generate documents. Think of them as variables that change for each document.

Template with merge fields:

Dear {{customer_name}} ,
Thank you for your order of {{product_name}} for ${{amount}}.

Becomes:

Dear John Smith,
Thank you for your order of Premium Widget for $299.

Basic Merge Field Syntax

Most automation tools use double curly braces:

{{field_name}} - Standard syntax
{{first_name}} - Replace with first name
{{email}} - Replace with email address
{{invoice_number}} - Replace with invoice number

Naming Conventions

Use underscores, not spaces:

✅ {{employee_name}}
❌ {{employee name}}

Be descriptive but concise:

✅ {{start_date}}
❌ {{d}} (too vague)

Use consistent casing:

✅ {{customer_name}} (snake_case - recommended)
✅ {{customerName}} (camelCase - also fine)
❌ {{CustomerName}} (PascalCase - avoid)

Common Merge Field Types

1. Text Fields

For names, addresses, descriptions:

{{full_name}}
{{company_name}}
{{job_title}}
{{address}}

2. Number Fields

For quantities, prices, IDs:

{{quantity}}
{{price}}
{{invoice_number}}

3. Date Fields

For dates (format in your data source):

{{start_date}} - Example: "January 15, 2024"
{{due_date}} - Example: "Net 15 days"
{{hire_date}} - Example: "03/15/2024"

4. Boolean (Yes/No) Fields

For conditional content:

{{is_remote}} - "Yes" or "No"
{{has_benefits}} - "True" or "False"

Advanced Techniques

Conditional Fields (If/Then Logic)

Show content only if a condition is met:

{{#if has_bonus}}
You are eligible for a ${{bonus_amount}} performance bonus.
{{/if}}

Calculated Fields

Some tools support formulas:

{{subtotal * 1.08}} - Add 8% tax
{{quantity * price}} - Calculate line total

List/Table Fields

For repeating data (like invoice line items):

{{#each line_items}}
{{description}} - ${{amount}}
{{/each}}

Best Practices

1. Match Data Source Exactly

Your Excel column headers must match merge fields exactly:

Excel header: customer_name

Template field: {{customer_name}}

2. Use Fallback Values

Provide default text for missing data:

{{middle_name || ""}} - Empty if no middle name
{{phone || "Not provided"}} - Show "Not provided" if blank

3. Test With Edge Cases

Test your template with:

Very long names
Special characters (apostrophes, accents)
Missing optional fields
Minimum and maximum values

4. Document Your Fields

Keep a list of all merge fields and their purpose:

Field Reference:

{{employee_name}} - Full name (required)
{{position}} - Job title (required)
{{salary}} - Annual salary with $ (required)
{{start_date}} - First day format: MM/DD/YYYY (required)

Common Mistakes

1. Typos in Field Names

Template: {{employe_name}} (missing 'e')

Data: employee_name

Result: Field doesn't populate!

2. Inconsistent Naming

Don't mix naming styles in one template:

❌ {{customer_name}} and {{customerEmail}}
✅ {{customer_name}} and {{customer_email}}

3. Missing Required Fields

Always check data has values for required fields before generating.

4. No Formatting in Data

Format data in your spreadsheet first:

Currency: $1,500 (not 1500)
Dates: January 15, 2024 (not 1/15/24)
Phone: (555) 123-4567 (not 5551234567)

Automate Your Document Templates

Master merge fields and generate hundreds of documents instantly. Join the waitlist.

Get Started Free

Testing Your Template

Create test data with 2-3 sample rows
Include edge cases (long names, special characters)
Generate test documents
Review for formatting issues
Check all fields populated correctly
Verify calculations if any

Quick Reference Cheat Sheet

Common Patterns:

Name fields: {{first_name}}, {{last_name}}
Contact: {{email}}, {{phone}}
Address: {{street}}, {{city}}, {{state}}, {{zip}}
Money: {{amount}}, {{price}}, {{total}}
Dates: {{date}}, {{due_date}}, {{start_date}}