Implementing Macros

23 min

Who is this for: Developers and partners who want to display personalized, dynamic content in offer creatives based on customer data.

Outcome: Implement macro placeholders in offer copy and configure payload data so MomentScience replaces them with real customer values-with fallbacks when data is missing.

Overview

Macros transform static offer messages into dynamic, personalized content by replacing placeholder variables with real customer and transaction data. This creates experiences that feel tailored to each user, increasing trust and conversion rates.

What you can achieve with macros::

Personalize greetings: Address customers by name when available

Confirm transactions: Display order numbers and purchase amounts

Adapt messaging: Show different content based on data availability

Maintain professionalism: Deliver grammatically correct messages regardless of missing data

How Macros Work

Macros are dynamic placeholders written as {{key}} that pull values from your data payload or URL parameters. When an offer displays, MomentScience replaces each macro with its corresponding value, or handles it gracefully if the data is missing.

Three ways to use macros:

Simple replacement: {{firstname}} becomes "Alex" when firstname data exists

Fallback values: {{firstname|'Valued Customer'}} displays a default when firstname is missing

Conditional logic: {{#if firstname}}Hey {{firstname}}, {{/if}} shows content only when data exists

This flexibility ensures your messages remain polished and professional in every scenario.

Macro Patterns

1. Simple Replacement : {{key}}

The most basic pattern replaces a placeholder with its value. If the value is missing, nothing is displayed.

Syntax: {{key}}

Example: Your order {{confirmationref}} is ready.

With data (confirmationref: "ORD-123") → Your order ORD-123 is ready.

Without data → Your order is ready. (leaves a blank space)

Use when: The field always has a value in your data flow.

2. Fallback Values: {{key|'default'}}

Provides a default value when data is missing, preventing blank spaces in your messages.

Syntax: {{key|'default value'}}

Example: Hello {{firstname|'there'}}!

With data (firstname: "Alex") → Hello Alex!

Without data → Hello there!

Use when: You want to substitute a specific alternative value rather than leaving the field empty.

3. Chained Key Fallbacks: {{key1|key2|'default'}}

Tries multiple payload keys in order, using the first one that has a value. If none are present, falls back to the static string.

Syntax: {{key1|key2|'static fallback'}}

Example: Hey {{firstname|lastname|'Guest'}}, welcome!

With firstname = "Alex" → Hey Alex, welcome!

Without firstname but with lastname = "Johnson" → Hey Johnson, welcome!

Without either → Hey Guest, welcome!

Rules:

Keys are tried left to right; the first non-empty value wins.

The static fallback must use single quotes and must be the last value in the chain.

You can chain as many keys as needed before the static fallback.

Use when: Multiple fields could plausibly hold the same content and you want the best available value.

4. Conditional Blocks: {{#if key}}...{{/if}}

Shows or hides entire sections based on whether data exists. This prevents awkward grammar and punctuation issues.

The Problem: Simple replacement creates broken grammar when data is missing:

Hey {{firstname}}, your order is confirmed.

Without firstname data, this renders as:

Hey , your order is confirmed.

The Solution: Wrap the entire greeting in a conditional block:

{{#if firstname}}Hey {{firstname}}, {{/if}}your order is confirmed.

Results:

With data (firstname: "Alex") → Hey Alex, your order is confirmed.

Without data → your order is confirmed. (clean, no awkward comma)

When the condition is false, the entire block, including "Hey", the space, and the comma, disappears, maintaining grammatically correct messages.

Use when: Entire phrases should appear or disappear based on data availability.

5. Conditional with Alternative: {{#if key}}...{{else}}...{{/if}}

Displays different content depending on whether data exists, giving you full control over both scenarios.

Syntax: {{#if key}}content when present{{else}}content when missing{{/if}}

Example:

{{#if firstname}}Hey {{firstname}}, {{else}}Hi there, {{/if}}your order is confirmed.

Results:

With data → Hey Alex, your order is confirmed.

Without data → Hi there, your order is confirmed.

Use when: You want to show different messages rather than simply hiding content.

When using macros through the Shopify integration, only {{first_name}} and {{last_name}} are supported. These macros will render only if the customer is logged in to their Shopify account at the time of purchase. If the customer checks out as a guest, no macros will be displayed.

For more information about configuring and personalizing offers with MomentPerks, refer to the Customizing MomentPerks Guide.

Macro Syntax Quick Reference

All macro patterns supported in Offer Unit messages:

Syntax	Description	Example	Result
{{key}}	Replace with value; empty if missing	Your order {{OrderID}} is ready.	Your order #1234 is ready.
{{key\|'default'}}	Use value, or default if missing	Hello {{firstname\|'there'}}!	Hello there! (when firstname is null)
{{#if key}}...{{/if}}	Show text only when value exists	{{#if firstname}}Hey {{firstname}}, {{/if}}your order is ready.	your order is ready. (when firstname is null)
{{key1\|key2\|'default'}}	Try each key in order; use static fallback if all are missing	Hey {{firstname\|lastname\|'Guest'}}, welcome!	Hey Guest, welcome! (when both keys are null)
{{#if key}}...{{else}}...{{/if}}	Show first option or fallback	{{#if firstname}}Hey {{firstname}}, {{else}}Hi, {{/if}}welcome back!	Hi, welcome back! (when firstname is null)

Combining Patterns

You can combine conditionals with simple replacements and fallbacks:

{{#if firstname}}Hey {{firstname}}, {{/if}}your order {{OrderID|'N/A'}} is confirmed.

When firstname = "Jon" and OrderID = "#5678":

Hey Jon, your order #5678 is confirmed.

When firstname is null and OrderID is null:

your order N/A is confirmed.

Recommended Macros

Macro	Description	Required in Payload
{{confirmationref}}	Passes the order or transaction confirmation number into the offer unit. This reassures users that their transaction is complete and draws attention to available offers.	confirmationref
{{firstname}}	Inserts the customer's first name into the offer unit. Personalizing content with a name encourages users to engage with the presented offers.	firstname
{{firstname\|'Hello'}}	Inserts the customer's first name with a fallback value. If firstname is not provided in the payload, displays 'Hello' instead.	Optional: firstname
{{#if firstname}}Hey {{firstname}}, {{/if}}	Conditionally displays greeting with first name. If firstname is missing, the entire greeting block is removed to prevent awkward punctuation.	Optional: firstname
{{payload_attribute}}	Any other custom attribute from your payload can be used as a macro for further personalization of the MomentScience unit.	The specific attribute name

Use these macros in your theme's text fields to dynamically insert relevant customer or transaction data, improving both user trust and conversion rates.

Best Practices

When to Use Each Pattern

Simple Replacement ({{key}}):

Use when the field is always present in your data

Example: Order confirmation numbers in post-purchase flows

Fallback Values ({{key|'default'}}):

Use when you want to substitute a specific alternative value

Example: {{firstname|'Valued Customer'}} provides a polite greeting alternative

Conditional Blocks ({{#if key}}...{{/if}}):

Use when entire phrases should appear or disappear based on data availability

Prevents awkward punctuation and maintains grammar

Example: {{#if firstname}}Hey {{firstname}}, {{/if}}your order is ready.

Conditional with Alternative ({{#if key}}...{{else}}...{{/if}}):

Use when you want different messages for different scenarios

Example: {{#if firstname}}Welcome back, {{firstname}}{{else}}Welcome{{/if}}

Implementation Steps

To dynamically render personalized content in your offer units, macro placeholders must be correctly defined and matched with values in your payload. If a value is missing, the placeholder will appear blank.

Using Javascript SDK

Step 1: Configure macros in your theme

Navigate to the Theme Customizer in your MomentScience dashboard.

In the Header or Lead-In Text fields, insert your macro placeholders using double curly braces {{ }}.

For example:

{{firstname}} to insert the customer's first name

{{firstname|'Valued Customer'}} to insert the first name with a fallback value

{{#if firstname}}Hey {{firstname}}, {{/if}}your order is confirmed for conditional greeting

{{amount}} for transaction amount

{{confirmationref}} for the order confirmation number

Use the preview panel to confirm the layout and styling render correctly with the placeholder macros.

The macro key used in the theme must exactly match the key provided in your payload with no spaces or special characters.

Example: use {{firstname}}, not {{ first name }}.

Step 2: Pass customer data in the payload

Add relevant customer and transaction data to your window.AdpxUser object:

window.AdpxUser = {
    email: "[email protected]",
    firstname: "Alex",
    lastname: "Johnson",
    confirmationref: "ORD-12345",
    amount: "$75.50",
    currency: "USD",
    paymenttype: "credit",
    zipcode: "10001",
    country: "US"
};

Use macros sparingly and purposefully, avoid overcrowding messages with variables

Step 3: Test the implementation

Test your implementation with various user scenarios to ensure macros render correctly in all cases.

No double spaces appear in the rendered message

Punctuation (commas, exclamation points) only appears when the value is present

Messages remain professional and natural in all scenarios

Fallback values display correctly when primary values are missing

Personalized result showing rendered macros

Using Direct Links

Perkswall supports macros across all offer content fields, allowing you to personalize user experiences without initializing through the SDK.

The following fields support macros on Perkswall:

Field	Description
Page Title	The header text displayed at the top of the Perkswall page.
Offer Headline	The primary title of each offer tile.
Short Headline	The condensed title used on mobile and compact display surfaces.
Description	The full offer description shown in Modal and Interstitial views on desktop.
Short Description	The condensed description used on mobile and on tiles, Featured Offers, and Standalone views.
Positive CTA	The primary call-to-action button text.
Negative CTA	The secondary or decline button text.

To pass macro values, include them as query parameters in the Perkswall URL. Each macro key corresponds to a parameter name, and when the link opens, Perkswall replaces placeholders (for example, {{firstname}}) with the provided values.

Example:

https://get.perkswall.com/?accountId=YOUR_ACCOUNT_ID&firstname=Jon&confirmationref=ORD-78910&amount=75.50

If your Title Text is: Thanks, {{firstname}}! Your order #{{confirmationref}} totaling ${{amount}} is confirmed.

It displays as: Thanks, Jon! Your order #ORD-78910 totaling $45.50 is confirmed.

Example Use Cases

Use Case	Message Template	Description
Personalized Offer Intro	{{#if firstname}}{{firstname}}, {{/if}}based on your purchase of {{amount}}, we've selected these offers for you.	Tailors offers post-purchase using customer name and order value. Gracefully handles missing names.
Offer Recommendations	Based on your purchase of {{amount}}, here are some offers you might like.	Suggests additional offers based on spend amount.
Order Confirmation	{{#if firstname}}Thank you, {{firstname}}! {{else}}Thank you! {{/if}}Your order #{{confirmationref}} is confirmed.	Confirms successful transactions with optional personalization.
Loyalty Enrollment	{{#if firstname}}Welcome, {{firstname}}! {{else}}Welcome! {{/if}}You've earned your first reward with order #{{confirmationref}}.	Welcomes new loyalty members with optional name personalization.
Localized Promotions	Exclusive deals for {{zipcode}}, {{country}} customers.	Displays location-based offers using ZIP code and country.
Payment Incentives	{{#if paymenttype}}Thanks for paying with {{paymenttype}}. {{/if}}Enjoy these special offers just for you.	Tailors messages based on payment method when available.

If you encounter any issues or need support during integration, contact us at [email protected].