Merge Fields & Modifiers: Practical Guide with Examples
This guide explains how to use merge fields and modifiers in your system, including examples for basic fields, signatures, prompts, place fields, buttons, lists, data modifiers, date formats, and combining modifiers.
1. How Do Basic Merge Fields Work?
Basic merge fields automatically insert information from your data into emails or PDFs.
- Emails: Use double curly braces:
{{fieldName}} - PDFs: Use just the field name:
fieldName
How it works in Pluto:
When you enter or update data (such as purchaser names, dates, purchase price, or addresses) in the Pluto Sales App, that information is stored in the system. When you generate a document or email using Pluto, the merge fields in your template (like {{purchaser-1-firstName}} or job-closingDate) are automatically replaced with the actual data from your records. This ensures that every document or email is personalized and accurate, without manual copy-pasting.
Examples:
| Purpose | Email Example | PDF Example |
|---|---|---|
| Purchaser's First Name | {{purchaser-1-firstName}} | purchaser-1-firstName |
| All Purchasers' First Names | {{purchaser-all-firstName}} | purchaser-all-firstName |
| Closing Date | {{job-closingDate}} | job-closingDate |
| Purchase Price | {{job-purchasePrice}} | job-purchasePrice |
| Community Name | {{community-name}} | community-name |
2. How Do Signature Fields Work for PDF Documents?
Signature fields define where and who should sign or initial a PDF. The field name determines the signer and type.
Examples:
| Scenario | PDF Field Name Example | Description |
|---|---|---|
| Developer signature | signature-developer | Developer signature block |
| Singular purchaser signature | signature-purchaser-1 | First purchaser signs |
| Singular purchaser initials | initials-purchaser-1 | First purchaser initials |
| Multiple purchasers' initials (down) | initials-purchaser-all-down | All purchasers initial (additional sign blocks expand down the page) |
| Singular realtor purchaser signature | signature-realtor | First realtor signs |
Notes:
- Use
signature-for signature blocks andinitials-for initials blocks - For initials, use all to include every purchaser or a number (e.g. 1, 2) to specify an individual.
- For signatures, use a number (e.g. 1, 2) to specify an individual purchaser.
- Add a direction (
left,right,down) for placing multiple intial blocks at a single location. This option is only valid when used in conjunction with theallsigners option
3. How Do Prompt Fields Work?
Prompt fields are used in PDFs to collect information from the user. Prompt fields should be named using the pattern: prompt-[type]-[fieldNameInCamelCase]
Replace [type] with the kind of input you want:
textfor a single-line text fieldtextareafor a multi-line text boxdatefor a date pickerdatetimefor a date and time pickerbooleanfor a checkbox (true/false)
Examples:
| Input Type | PDF Field Name Example | Description |
|---|---|---|
| Single-line text | prompt-text-customerName | User enters their 'Customer Name' |
| Multi-line text | prompt-textarea-customerNotes | User enters 'Customer Notes' |
| Date picker | prompt-date-dateOfBirth | User enters 'Date of Birth' |
| Checkbox | prompt-boolean-agreeToTerms | User checks to 'Agree to Terms' |
| Number input | prompt-text-customerAge | User enters their age 'Customer Age' |
Note:
- Always use camelCase for the field name at the end of the text for multiple words you would like shown for a Prompt area (e.g.,
customerName,dateOfBirth). - We use camelCase to clearly separate words in a single string without spaces or underscores, making each new word easy to spot by its capitalized first letter. For example, the field name
prompt-text-customerNamewould be shown to the user as "Customer Name" in the data entry text field.
4. Placeholders
Placeholders are special fields used by the program to insert dynamic or interactive content in documents.
Note: Placeholders are only used for System Templates. They are not available for custom or user-created templates.
Examples:
For Emails (Device Verification Email)
| Purpose | Email Field Name Example | Description |
|---|---|---|
| Verification code | {{placeholder-verificationCode}} | Generates a new verification code and inserts it into the email |
| Code expiry (minutes) | {{placeholder-codeExpiryMinutes}} | Adds the number of minutes before the code expires |
For PDFs (Internal Options PDF)
| Purpose | PDF Field Name Example | Description |
|---|---|---|
| Option description | {{placeholder-description}} | Displays the name/description of the internal change order option |
| Option quantity | {{placeholder-quantity}} | Shows the quantity for the internal option |
| Option rate | {{placeholder-rate}} | Shows the price per one unit of the internal option |
| Option total price | {{placeholder-price}} | Displays the total price (rate × quantity) for the internal option |
Special:
- Placeholders are not just for displaying data—they can create interactive elements or mark spots for system-generated content.
- The program recognizes these fields and handles them differently from standard data fields.
5. Button Fields (Emails Only)
Button fields are used in emails to insert interactive buttons that perform specific actions or link to important pages.
Use double curly braces for button fields in emails: {{button-[type]}}
Examples:
| Purpose | Email Field Name Example | Description |
|---|---|---|
| Link to a webpage | {{button-link}} | Button that opens a specified link to Email |
| Identity verification | {{button-identityVerification}} | Button that opens a link for the recipient to verify their identity for customer connect |
| Advanced registration | {{button-advancedRegistration}} | Button that opens a link to start an advanced registration process for customer connect |
| View reservation | {{button-viewReservation}} | Button that opens a link to view reservation details for customer connect |
Note:
- The button type (e.g.,
link,identityVerification,advancedRegistration,viewReservation) determines the action or destination of the button. - These buttons are only supported in emails, not in PDFs.
6. Working with Lists vs. Specific Items in Lists
You can reference all items in a list or a specific item.
When working with lists (such as purchasers on a job), you can use special keywords or numbers in the field name to control which items you want to access:
- Use
allin the field name (e.g.,purchaser-all-firstName) to get information for all purchasers related to a particular job. This will return a combined result (such as a comma-separated list) of the specified field for every purchaser. - If you want information for a specific purchaser, use a number in the field name (e.g.,
purchaser-1-firstNamefor the first purchaser,purchaser-2-emailfor the second purchaser, etc.). The number represents the position of the purchaser in the list for that job.
Note:
Not all lists support the all keyword. Some lists may only allow referencing specific items by number. Please refer to our Fields documentation to find out which merge fields do not support the all keyword.
Examples:
| Purpose | Field Name Example | Description |
|---|---|---|
| All purchasers | purchaser-all-firstName | All purchasers' first names |
| First purchaser | purchaser-1-firstName | First purchaser's first name |
| Second purchaser | purchaser-2-email | Second purchaser's email |
7. Data Modifiers: What Are They & Examples
Data modifiers change how a field's value is displayed or calculated. Add a modifier after the field name, separated by a dash, with arguments in parentheses.
Types & Examples:
| Modifier | Purpose | Example Usage | Result Example |
|---|---|---|---|
format | Format value (date, number) | job-closingDate-format(d MMMM yyyy) | 5 June 2025 |
add | Add to value (number/date) | job-totalPrice-add(5000) | Adds $5,000 to total price |
percent | Calculates the amount base on the percentage you put in the brackets | job-commissionTotal-percent(50) | Show 50% of commission total (calculated) |
8. Using the Percentage Modifier
You can use the percent modifier to display a calculated amount based on a percentage of a value, such as a commission.
The percent modifier does the calculation for you, showing the actual amount that represents the given percentage of the base value.
Example:
| Purpose | Field Name Example | Description |
|---|---|---|
| Show 50% of the commission total amount | job-commissionTotal-percent(50) | Shows the amount that is 50% of the commission total for the job |
How it works:
- The
percentmodifier calculates the specified percentage of the field's value and displays the resulting amount. - For example, if the commission total for the job is $10,000, then
job-commissionTotal-percent(50)will display$5,000. - You can use this for any valid commission total merge field with the percent modifier.
9. Common Date Format Patterns & Usage with Date Modifier
Date format patterns control how dates appear. Use with the format modifier.
| Format String | Example Output | Description |
|---|---|---|
d MMMM yyyy | 5 June 2025 | Day Month Year (month as text) |
MMMM yyyy | June 2025 | Month Year |
yyyy | 2025 | Year only |
MMMM | June | Month only (text) |
MM | 06 | Month only (number) |
d | 5 | Day only |
dd | 05 | Day only (2 digits) |
M/d/yyyy | 6/5/2025 | US short date |
yyyy-MM-dd | 2025-06-05 | ISO date format |
dd MMM yyyy | 05 Jun 2025 | Day (2 digits) Short Month Year |
MMM yyyy | Jun 2025 | Short Month Year |
d-MMM-yy | 5-Jun-25 | Day-ShortMonth-2digitYear |
In Use:
Email:
{{job-closingDate-format(d MMMM yyyy)}}PDF:job-closingDate-format(d MMMM yyyy)
Real Case Scenario: If closing date is June 5, 2025:
job-closingDate-add(d MMMM yyyy)→ 5 June 2025job-closingDate-add(d MMMM yyyy)→ 5 June 2025
10. Add Modifiers: Examples for Numbers & Dates
Add can be used to increase or decrease numbers or dates of the given merge field.
Add to Numbers
Add $5,000 to purchase price:
job-totalPrice-add(5000)
Add to Dates (Add Days)
Add 7 days to closing date:
job-closingDate-add(7)Subtract 3 days from closing date:job-closingDate-add(-3)
Real Case Scenario: If closing date is June 5, 2025:
job-closingDate-add(7)→ June 12, 2025job-closingDate-add(-3)→ June 2, 2025
11. Boolean Modifer
1. yesOrNo
- Purpose: Outputs
"Yes"or"No"based on a boolean or status value. - Example Usage:
- Field:
homeowner-[]-isResident - If the homeowner is a resident, the field returns
"Yes". Otherwise, it returns"No".
- Field:
2. xOrNoX
- Purpose: Outputs
"X"or an empty string, often used for checkboxes in forms. - Example Usage:
- Field:
homeowner-[]-isResident - If the homeowner is not a resident, the field returns
"X"(to check the box). Otherwise, it returns""(leave the box unchecked).
- Field:
Summary Table: Modifiers
| Modifier | Usage Example | Description |
|---|---|---|
| format | job-closingDate-format(MMMM yyyy) | Formats the closing date as "June 2025" |
| add | job-purchasePrice-add(5000) | Add 5,000 to total purchase price |
| add (date) | job-closingDate-add(7) | Add 7 days to closing date |
| percent | job-commissionTotal-percent(50) | Show 50% of commission total (calculated) |
| yesOrNo | homeowner-[]-isResident-yesOrNo | "Yes" or "No" based if the boolean value is True or False |
| xOrNo | homeowner-[]-isResident-xOrNo |
12. What Are Backfills?
Backfills are special fields that are populated after the contract is created, rather than during the contract creation process. They are filled in automatically when an signature event occurs.
Backfills are useful for capturing important dates or statuses that depend on actions taken after the initial contract is generated. This ensures that the document always reflects the most up-to-date information, even if those events happen later in the process.
Current Uses for Backfills: [offerDate & contractDate only on main contract ]
- offerDate: Populated with today's date when all purchasers have signed the main contract.
- contractDate: Populated with today's date when developer has signed the main contract.
- purchaserSignedDate: Populated with today's date when all purchasers have signed.
- developerSignedDate: Populated with today's date when all developers have signed.
Example:
If you include a backfill field like backfill-offerDate in your document, it will remain empty until all purchasers have signed. Once that signature event occurs, the system will automatically populate the current date in that field.