Implementing Macros

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 docid\ jcczrozbi5d0pvdqm15kx 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 "customer\@example com", 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 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 help\@momentscience com mailto\ help\@momentscience com