Hi {{customer.first_name}},
Your order total was {{formatCurrency amount_total}}.
``` Rendered output: ```htmlHi George,
Your order total was $89.99.
``` --- ## Where Handlebars Can Be Used Handlebars can be used in: - Subject - From address - From name - To - CC - BCC - HTML body Most templates use Handlebars primarily in subject and HTML body, but recipient fields can also be dynamic. --- ## Common Handlebars Patterns ### Basic Substitution ```handlebars Hello {{customer.first_name}} ``` ### Conditional Content ```handlebars {{#if customer.first_name}}Hello {{customer.first_name}},
{{else}}Hello,
{{/if}} ``` ### Loop Over Products ```handlebars{{../customer.first_name}} purchased {{name}}
{{/each}} ``` --- # Custom Handlebars Helpers RevCent supports standard Handlebars plus custom helpers. ## `formatDate` Formats a valid ISO date or Unix timestamp. ```handlebars {{formatDate created_date_unix 'MM/DD/YYYY' '-0500'}} ``` Notes: - Default format is `MM/DD/YYYY`. - Timezone offset is optional. - You can use `now` to format the compilation/send-time timestamp. Example: ```handlebars {{formatDate now 'MM/DD/YYYY' '-0500'}} ``` --- ## `formatCurrency` Formats a number using the `iso_currency` value in the input data. ```handlebars {{formatCurrency amount_total}} ``` Example: ```handlebarsTotal: {{formatCurrency amount_total}}
``` --- ## `findWhereEquals` Finds a value inside an array of objects. Format: ```handlebars {{findWhereEquals 'metadata' 'name' 'affiliate_id' 'value'}} ``` Meaning: - Search the `metadata` array. - Find the object where `name` equals `affiliate_id`. - Return that object’s `value`. Example: ```handlebars Affiliate ID: {{findWhereEquals 'metadata' 'name' 'affiliate_id' 'value'}} ``` --- ## `math` Performs a calculation between two values. Format: ```handlebars {{math 'add' shipping_amount tax_amount 'currency'}} ``` Supported operations: - `add` - `subtract` - `multiply` - `divide` Supported output formats: - `integer` - `float` - `currency` Example: ```handlebarsShipping + tax: {{math 'add' shipping_amount tax_amount 'currency'}}
``` --- ## Type and Case Helpers ```handlebars {{parseInt amount}} {{parseFloat amount}} {{toString amount}} {{startCase customer.first_name}} {{upperCase customer.first_name}} {{lowerCase customer.first_name}} ``` Use these for formatting data without needing a Function. --- # Trigger-Specific Input Data The selected Email Template trigger determines the input data available to Handlebars. This is one of the most important concepts. If the trigger is sale-related, the template receives Sale JSON. If the trigger is customer-related, it receives Customer JSON. If the trigger is shipping-related, it receives Shipping JSON. Example: For a Sale trigger: ```handlebars {{customer.email}} {{customer.first_name}} {{amount_total}} ``` For a Customer Created trigger: ```handlebars {{email}} {{first_name}} {{last_name}} ``` Do not assume the same path works for every trigger. --- ## Input Data JSON Links Use these JSON files as source-of-truth examples for Handlebars paths. | Source Object | Input Data JSON | |---|---| | Sale | `https://revcent.com/documentation/files/email_template/input_data/sale.json` | | Sentinel | `https://revcent.com/documentation/files/email_template/input_data/sentinel.json` | | AI Memo | `https://revcent.com/documentation/files/email_template/input_data/ai_memo.json` | | Fraud Detection | `https://revcent.com/documentation/files/email_template/input_data/fraud_detection.json` | | Invoice | `https://revcent.com/documentation/files/email_template/input_data/invoice.json` | | Customer | `https://revcent.com/documentation/files/email_template/input_data/customer.json` | | Pending Refund | `https://revcent.com/documentation/files/email_template/input_data/pending_refund.json` | | Shipping | `https://revcent.com/documentation/files/email_template/input_data/shipping.json` | | Subscription Renewal | `https://revcent.com/documentation/files/email_template/input_data/subscription_renewal.json` | | Subscription | `https://revcent.com/documentation/files/email_template/input_data/subscription.json` | | Trial | `https://revcent.com/documentation/files/email_template/input_data/trial.json` | --- # Email Template Triggers Email Template triggers determine when an email sends and what input data the template receives. ## Direct Triggers | Trigger | Purpose | Input Data | |---|---|---| | No Trigger | Draft or external-process template. | None | | API/AI | Trigger email via API or AI System Tool. | None by default; uses custom arguments/custom data. | --- ## Event Triggers | Trigger | Ecommerce Use Case | Input Data | |---|---|---| | AI Memo Created | Notify a user/team when an AI Assistant creates a memo. | AI Memo | | Customer Created | Welcome new customers or notify internal teams. | Customer | | Fraud Detection Created | Notify fraud/risk team. | Fraud Detection | | Invoice Create Success | Send invoice link or notify accounting. | Invoice | | Pending Refund Created | Notify support/accounting that refund is pending. | Pending Refund | | Sale Success | Send receipt or fulfillment instructions. | Sale | | Sale Fail | Send failed-payment notice or internal alert. | Sale | | Sale Fraud Alert | Notify manual review team. | Sale | | Sale Pending No Payment | Abandoned-cart reminder. | Sale | | Sentinel Alert | Notify risk/security team. | Sentinel | | Shipping Item Created | Notify warehouse or fulfillment team. | Shipping | | Shipping Item Shipped | Send tracking email to customer. | Shipping | | Shipping Item Delivered | Send delivery confirmation. | Shipping | | Shipping Item Voided | Notify warehouse/support of cancellation. | Shipping | | Subscription Renewal Success | Confirm renewal. | Subscription Renewal | | Subscription Renewal Fail | Notify customer or support of failed renewal. | Subscription Renewal | | Subscription Renewal Upcoming | Send upcoming renewal reminder. | Subscription | | Trial Expire Success | Confirm successful trial conversion/expiration. | Trial | | Trial Expire Fail | Notify of trial expiration payment failure. | Trial | | Trial Expire Upcoming | Send trial ending reminder. | Trial | --- ## Trigger Timing Email Templates can send immediately or at a specific time relative to the trigger. ### Immediate Send the email immediately when the trigger occurs. Best for: - Receipts - Shipment updates - Fraud alerts - Internal notifications - Invoice created emails ### Specific Timing Send before or after the trigger by a defined amount of time. Settings: | Setting | Meaning | |---|---| | Time Relative | Before or after the trigger. | | Time Unit | Hours, days, weeks, months, years. | | Time Value | Number of units. | Examples: Send three hours after a sale: ```text Time Relative: After Time Unit: Hours Time Value: 3 ``` Send one day before a subscription renewal: ```text Time Relative: Before Time Unit: Days Time Value: 1 ``` Important: - `before` timing applies to predictable upcoming events such as subscription renewal upcoming and trial expire upcoming. - `after` timing is useful for follow-up emails, abandoned cart reminders, and delayed internal checks. --- # Filters and Template Settings Filters let you restrict when a template is allowed to send. Common filters: | Filter | Purpose | |---|---| | Campaigns Allowed | Only send for selected campaigns. | | Third Party Shops Allowed | Only send for selected shops. | | Product Groups Allowed | Only send for selected product groups. | | Products Allowed | Only send for selected products. | | Products Visible | Control which products are visible/listed in the email. | Use filters when: - Different brands need different emails. - Different campaigns need different copy. - Certain products require special instructions. - Third-party shops need different fulfillment notifications. - Internal alerts should only fire for specific campaigns or products. Example: A store may use one Sale Success receipt for Product A and another for Product B. --- # Custom Data Custom data adds extra values to the Handlebars input data under `custom_data`. Custom data can come from: 1. A static JSON object. 2. A RevCent Function. --- ## Custom Data from JSON Use JSON custom data when values are static or simple. Example custom data: ```json { "support_email": "support@example.com", "brand_name": "Example Brand", "footer_text": "Thanks for being a customer." } ``` Template usage: ```handlebars{{custom_data.footer_text}}
Support: {{custom_data.support_email}}
``` Best for: - Brand names - Support emails - Static disclaimers - Campaign text - Store URLs - Simple custom messages --- ## Custom Data from a Function Use a RevCent Function when custom data must be computed dynamically. The Function must use the Email Template trigger type. The Function receives the same item details as the Email Template at: ```javascript event.data.item_details ``` The Function must return a plain JSON object. Example Function: ```javascript let customerEmail = event.data.item_details.customer.email; callback(null, { email_capitalized: customerEmail.toUpperCase(), email_local_part: customerEmail.split("@")[0], custom_footer: "Thank you for your purchase." }); ``` The returned object becomes: ```json { "custom_data": { "email_capitalized": "GEORGE@EXAMPLE.COM", "email_local_part": "george", "custom_footer": "Thank you for your purchase." } } ``` Template usage: ```handlebars{{custom_data.custom_footer}}
Email local part: {{custom_data.email_local_part}}
``` --- ## Advanced Custom Data Use Cases Functions can generate custom email data such as: - Product recommendations. - Dynamic coupon codes. - Loyalty status. - External CRM attributes. - Custom support routing. - AI-generated paragraphs. - Dynamic legal or compliance language. - Shipment-specific instructions. - Personalized renewal offers. - Customer segmentation labels. - Abandoned-cart incentives. Example: A sale receipt Function can create a customer-specific coupon: ```javascript let firstName = event.data.item_details.customer.first_name || "CUSTOMER"; callback(null, { coupon_code: `${firstName.toUpperCase()}25`, coupon_discount: "25%" }); ``` Template usage: ```handlebarsUse code {{custom_data.coupon_code}} for {{custom_data.coupon_discount}} off your next order.
``` --- # API/AI Direct Email Templates API/AI direct templates are sent explicitly through API or AI rather than automatically from a RevCent event. Use cases: - AI sends a custom follow-up email. - Support triggers a manual email. - API sends transactional messages from an external workflow. - AI generates a personalized subject/body section. - A template is used as part of a broader automated process. ## Custom Arguments Custom arguments allow runtime values to be inserted into the template. Example custom argument names: ```text recipient_email subject_line personalized_intro message_body recommended_product ``` Template usage: ```handlebars {{custom_arguments.recipient_email}} {{custom_arguments.subject_line}} {{custom_arguments.personalized_intro}} ``` Example template: ```handlebars{{custom_arguments.personalized_intro}}
{{custom_arguments.message_body}}
``` Important: - Custom arguments are most useful for API/AI direct templates. - AI can generate custom argument values based on the descriptions provided. - Descriptions should be specific and clear. Good description: ```text Write a warm one-sentence opening line using the customer's first name and the product they purchased. ``` Poor description: ```text intro ``` --- # Additional Shortcodes Additional shortcodes can be used in subject or body. | Shortcode | Applies To | Meaning | |---|---|---| | `{{item_date}}` | All triggers | Date of the item relative to the trigger, such as sale date or renewal date. | | `{{date_now}}` | All triggers | Current date when the email is sent. | Example: ```handlebarsEmail sent on {{date_now}}.
Item date: {{item_date}}.
``` --- # Editors and Preview ## Design Editor The Design Editor is a WYSIWYG HTML editor. Use it for: - Basic layout - Text edits - Logo changes - Simple shortcodes - Styling adjustments For complex Handlebars logic, the Code Editor is usually better. --- ## Code Editor The Code Editor exposes raw HTML. Use it for: - Handlebars conditionals - Loops - Complex table layouts - Custom HTML - Dynamic sections - More precise styling Important: - Remote stylesheets and `