Merge tags are a feature of Ninja Forms that allows data to be pulled from different sources within WordPress and populated in the location that the merge tag is placed. They can be used to pre-populate fields with logged in user metadata, pass field data from one form to another, populate email messages with the name of the submitter, and much more.
Please note that if a merge tag refers to data that does not exist at the time the user submits the form (for example, the submission ID or payment details), it will not populate within fields within the form submission and should only be used in the contents of actions, such as emails, that occur after the submission is recorded.
Below is a comprehensive list of available merge tags and their functions.
Table of Contents
- Using Merge Tags
- Actions Merge Tags
- User Meta Merge Tags
- Site Merge Tags
- Post/Page Merge Tags
- Other Merge Tags
- Plugin Specific Merge Tags
Using Merge Tags
Merge tags can be entered manually, or selected within the builder anywhere you see a merge tag icon. For example:
In addition to the merge tags listed below, each time you add a field to your form a unique merge tag is generated for that field. These can be accessed on the Fields tab of the merge tag popup when the merge tag icon is clicked:
Actions Merge Tags
Fields Table {fields_table} – This returns the labels and submission data* for all of the fields that have had data entered into them.
All Fields Table {all_fields_table} – This returns the labels and submission data* for all fields, including HTML fields, even if they do not have data submitted into them.
*Note: in the case of List fields, the option labels are returned for the options selected, not the data values of those options.
List values can be accessed by enabling Developer Mode in the settings. Enabling Developer Mode or simply navigate to Ninja Forms > Settings > Advanced Settings and check the box for “Form Builder Dev Mode”, then save settings.
User Meta Merge Tags
User ID {wp:user_id} – This returns the User ID for the logged in user
Username {wp:user_username} – This returns the username of the logged in user
User First Name {wp:user_first_name} – This returns the First Name for the logged in user
User Last Name {wp:user_last_name} – This returns the Last Name for the logged in user
User Display Name {wp:user_display_name} – This returns the Display Name for the logged in user
User Email {wp:user_email} – This returns the Email address for the logged in user
User URL {wp:user_url} – This returns the information stored as the Website for the logged in user
User Meta {user_meta:YOUR_META_KEY} – This will return the meta value from the user meta in WordPress for the logged in user associated with the meta key that you include in the merge tag.
Site Merge Tags
Site Title {wp:site_title} – This returns the Title of the site
Site URL {wp:site_url} – This returns the URL of the site
Admin Email {wp:admin_email} – This returns the server admin email address set on the WordPress General settings page
Post/Page Merge Tags
Post ID {wp:post_id} – This returns the ID of the Post/Page the form is on.
Post Title {wp:post_title}– This returns the Title of the Post/Page the form is on.
Post URL {wp:post_url} – This returns the URL of the Post/Page the form is on.
Post Author {wp:post_author} – This returns the Name of the Author of the Post/Page the form is on.
Post Author Email {wp:post_author_email} – This returns the Email of the Author of the Post/Page the form is on.
Post Permalink {post:permalink} – This returns the Permalink URL of the Post/Page that is being created by the Create Post action. Please note that this merge tag is only available in the form builder when the Post Creation add-on is active.
Post Meta {post_meta:YOUR_META_KEY} – This will return the meta value from the post meta in WordPress for the current post associated with the meta key that you include in the merge tag.
Other Merge Tags
Submission Count {submission:count} – This is used in an HTML field to display to the user how many submissions have been made on the form.
Submission Sequence {submission:sequence} – This merge tag is used to get the submission number of the current user’s submission. This merge tag only populates after the submission data has been saved to the database and requires a Record Submission action to be activated on the form.
Random {other:random} – This returns a random five character string.
Date {other:date} – This records the date that the submission is made. The format of the date is set in the Ninja Forms settings. The data from this merge tag is not populated until after the data is saved in the submission.
Time {other:time} – This records the time that the submission is made. The format of the time is set based of the WordPress language settings for time. The data from this merge tag is not populated until after the data is saved in the submission.
User IP Address {other:user_ip} – This returns the IP address the form is being submitted from.
Query String {querystring:YOUR_KEY} – The use of this merge tag is documented here.
List Field Merge Tag Modifier
:label – This merge is only usable with list field merge tags in the Emails & Actions section of Ninja Forms. When a list merge tag ends with :label the label text will be output instead of the value.
List values can be accessed by enabling Developer Mode in the settings. Enabling Developer Mode or simply navigate to Ninja Forms > Settings > Advanced Settings and check the box for “Form Builder Dev Mode”, then save settings.
Plugin Specific Merge Tags
PayPal Checkout:
Order ID {nfpaypal:order_id} – This returns the Order ID from the PayPal payment. The data from this merge tag is not populated until after the payment is made. This only populates when a PayPal Checkout action is completed.
PayPal Express:
Transaction ID {paypal_express:transaction_id} – This returns the Transaction ID from the PayPal payment. The data from this merge tag is not populated until after the payment is made. This only populates when a PayPal Express action is completed.
PayPal Express is a legacy add-on that is still being supported but is no longer available for purchase. It will be sunset / removed by the end of 2024.
Please see here for more information on migrating PayPal Express to PayPal Checkout.
Stripe:
Last 4 {stripe:last4} – This returns the last 4 digits of the Credit Card from the Stripe payment. The data from this merge tag is not populated until after the payment is made.
Card Type (Brand) {stripe:cardtype} – This returns the Credit Card type from the Stripe payment. The data from this merge tag is not populated until after the payment is made.
Customer ID {stripe:customerID} – This returns the Customer ID from the Stripe payment. The data from this merge tag is not populated until after the payment is made.
Charge ID {stripe:chargeID} – This returns the Charge ID from the Stripe payment. The data from this merge tag is not populated until after the payment is made.
User management:
Password Reset {user_management:password_reset} – This will output a link to your WordPress install’s password reset page /wp-login.php?action=lostpassword
Logout {user_management:logout} – This will log the user out of your WordPress site.
File Uploads:
Filename {file:name} – This returns the name of the uploaded file along with its file extension type.
File Extension {file:extension} – This returns the extension type, whether it is a jpeg, pdf, png, etc.
Use the merge tag for the File Upload field to output the URL for the File Upload location
Merge Tag Modifiers
:embed – When a File Upload merge tag ends with :embed the output will be formatted to embed an image.
:pdf_embed – Used in conjunction with the PDF Form Submissions add-on; append to the File Upload field merge tag in the PDF body customization options to embed an image file rather than a link to that file.
:link – When a File Upload merge tag ends with :link the output will be formatted as a link.
:url – When a File Upload merge tag ends with :url the output will be formatted as the full URL