Create notification templates and conditions

The Advanced (v2) notification system includes one predefined Default template for each of the following notification methods:

• Email
• SMS
• Off platform

Marketplace Managers can define one or more custom notification templates for each notification method. The v2 notification system uses these templates to generate and send a notification for a given marketplace event and its associated notification type (for example, the Product Purchased notification type). For email and SMS templates, custom templates can include (but are not required to include) user-defined notification conditions. If configured, conditions are used to evaluate which—if any—of the custom templates is used to generate and send a notification. If the notification system determines that none of the custom templates are appropriate for the associated event, it uses the predefined Default notification template to generate the notification.

For off-platform templates, only template priority determines which template is used. Conditions and segments that you add in the UI are not evaluated at runtime. Use priority order to choose among off-platform templates.

You can also target email and SMS notifications to specific customer segments. For example, you can create a new version of a notification and target that new template to a specific group of customers. In order to do this, you need to have previously created segments. For more information, see Segments.

For email and SMS, you can add one or more conditions, or add segments, or you can define both conditions and segments.

How segments select templates (email and SMS)

The following applies to email and SMS notification templates only. Off-platform templates are selected by priority only; segments and conditions configured on off-platform templates are ignored at runtime even though the UI lets you add them.

Segments and audience fields do different jobs:

• Segments — Determine which template is used for the notification.
• To / Cc / Bcc — Determine who receives the email after the template is chosen (email only).

The system does not choose a template based on who is listed in To, Cc, or Bcc. Segment matching uses the user UUID published on the notification event. That user depends on the notification type. For many subscription and order notifications (for example, Product Upgraded), it is the order creator, shown as Product Owner in the notification. For other types—such as Invoice PDF created—it can be a different user, such as the invoice customer. Everyone included in the send receives the same selected template.

How template selection works

1. A marketplace event triggers a notification (for example, a subscription upgrade).
2. The system evaluates enabled templates for that notification type in priority order (lowest priority number first). See Set notification template priority.
3. For a template that includes segments, the system checks whether the event user belongs to one of those segments.
4. The first matching template is used. If no segment (or condition) rule matches, a broader or Default template is used as a fallback.
5. After the template is selected, the To / Cc / Bcc settings on that template determine the recipients.

📝 Note: Creating a segment under Manage > Marketplace > Products > Groups is not enough by itself. You must also add the segment on the notification template and give that template a higher priority than broad fallback templates (for example, a Default or general custom template with no segment).

Example: Reseller-assisted purchase

If a reseller places the order and their user UUID is not in the segment on your custom template, the segment rule does not match. The system uses the fallback template, and the email still goes to whoever is configured in To / Cc / Bcc. To use the segment-specific template for reseller-assisted orders, include the reseller’s user UUID in the segment.

Billing notifications: which user drives segment matching (email and SMS)

Segment matching uses the user UUID on the notification event. That user is not always the same as the default To recipient shown in Notification template content. There is no single rule across all notification types—each type publishes the user that drives segment lookup.

Use the following table when you configure segments for common billing notifications. Add the listed user to your segment if you want that template rule to match. Users listed only in To / Cc / Bcc (for example, Billing Admin or account manager) do not drive segment matching.

Notification (examples)	User used for segment matching
Product purchased, Product Upgraded, subscription cancel or suspend, scheduled contract changes, End of Contract, Failed order, offline order	Order creator (shown as Product Owner in many billing notifications)
Free trial started, Free trial expired, Free trial auto-upgrade warning	Order creator
Subscription adoption	New subscription owner
Adoption notice, Discount deactivated	Subscription owner (company entitlement owner)
New Invoice Created, Invoice	Invoice customer user
Invoice PDF Created, Credit memo PDF created	Invoice or credit memo customer user
Payment Successful, Payment Failed, Refund Issued	Payment event user or payment method owner (depends on how the notification is published for your marketplace)
Credit Card Expiration Warning	Payment instrument owner
Add Payment Method Request	End user who receives the request (not the reseller who triggered it)
Customer Balance notification	Segment matching is not available—no user UUID is published on the event

📝 Note: For reseller-assisted purchases, use the reseller’s user UUID in the segment when the reseller is the order creator. Billing Admin, Sales Representative, or other roles in To / Cc / Bcc do not affect which template is selected.

The notification system also evaluates each condition in each email or SMS template associated with a notification type to determine if the template evaluates to True. The first template that evaluates to True (that is, all of a template's conditions evaluate to True) is used to generate and send a notification for the associated event. Each condition includes three elements—a parameter, an operator, and a value—that construct a logical phrase that the notification system evaluates to determine whether it matches the marketplace event.

Whether or not a template is sent is also defined by whether or not it is set to be triggered. For more information, see Set notification template priority.

To create a notification template

1. Go to Manage > Marketplace > Settings > Custom UI | Notifications. The Notifications page opens.

2. Click the row of the notification for which you want to define a new notification template. The default email template opens. Depending on your settings, three notification types might appear: Email, SMS, and Off-platform.

3. (Optional) Click one of the other delivery methods for the new template: SMS or Off platform. The Default template appears for the selected delivery method. If you click Off platform, you must enter a target URL for the Default template before you add a new template.

4. Click the Default drop-down button, then select + New Template from the drop-down list. The Create New Template page opens.

5. Enter a template name. The template name cannot contain spaces but can contain special characters, including dashes, underscore, and so on.

6. Enter a description.

7. (Optional) Click Add Condition. The Create a Condition dialog opens. Conditions apply only to email and SMS templates. On Off platform templates, conditions are not evaluated at runtime.

   1. Select a predefined option from the Parameter drop-down menu. The parameter is the entity to which the condition is applied. Parameters represent a general classification (for example, a company) while the value is specific (a company named Acme). The available parameters differ from one notification type to another (for example, applicationID is included in the Product Purchase notification type, but not in the New Account Created notification type).
   2. Select an option from the Operator drop-down menu. The operator determines the relationship between the condition’s parameter and value. For example, the operator equals states that the parameter must match the value (companyName equals Acme). The available operators are as follows:
      • Equals
      • Does not equal
      • Contains
      • Does not contain
      • Includes any of
      • Does not include any of
   3. Enter a value in the Value field. The value is the specific data used with the parameter and operator for evaluation. The value is the specific information compared to the parameter's more general information.
      Note the following when entering values:
      • Value field entries are case sensitive: mycompany does not match MyCompany.
      • If you selected either includes any of or does not include any of in the Operator field (in step c), enter the values using comma-separated entries, for example, entry1, entry2, entry3 or entry1, entry2, entry3.
   4. Click Save Condition. The condition is created and associated with this template. It appears in the Conditions table in the New Template Setup dialog.
   5. (Optional) Repeat this step to add additional conditions as required. When templates with multiple conditions are evaluated, all conditions must evaluate to True for the template to evaluate to True and be selected to generate the notification. If any of this template's conditions evaluate to False, the template is rejected and the template with the next highest priority is evaluated.

8. (Optional) If you do not want this template to send a notification if it evaluates to True, click the Do not send notifications matching these conditions toggle.

9. (Optional) To ensure the condition's combination of parameter, operator, and value are accepted by the notification type's structural definition (also known as the schema), click Validate Conditions.
   For example, if your condition includes the applicationName parameter, the contains operator, and the soft value, you can test it to see whether it is valid for either or both of Microsoft Office365 and MuleSoft Anypoint Design Center. For more information, see Validate notification template conditions.

10. (Optional) To add segments, select a segment folder in the left column of the Segments pane, then select segments to add to the template. You can add as many segments as needed. Segments apply only to email and SMS templates. On Off platform templates, segment settings are not evaluated at runtime—use template priority to choose among off-platform templates instead.

11. Configure the audience. The To field is pre-configured to be the intended recipient type for the notification but you can add email addresses to the cc and bcc fields.

12. Configure the email content, as follows:

    • Language
    • Subject line
    • Body content

13. (Optional) Add parameters to the template, if required. Parameters are variables that serve as placeholders in the template. When the notification is generated, the system replaces the parameter with the appropriate value. For more information about the list and descriptions of available parameters, see Parameter descriptions. After you click on a parameter, it appears where your cursor is placed in the template. You can also click and drag the parameter to a specific place in the template. Note the following:

    • Advanced parameters contain nested properties or are organized in an array. When you add advanced parameters to a template, you must update them manually in a dot-separated format (for example, user.address.city). Advanced parameters are available for a limited number of email notification templates—for example, the Product Purchased template.
      For example, to include a table that contains all of the order items in the purchase order, you can use the following HTML code:

    <table>
    {​th:for-each=$orders}
    <tr>Order Id </tr>
    <tr>{​orders[i].id} </tr>
    {​th:for-each}
    </table>

    • The Custom attribute parameters pane only includes attributes that the Marketplace Manager defined as company attributes (see Set custom attributes for more information). After you add a custom attribute parameter, to ensure that the email notification includes both the custom attribute's label and its associated value, add .label and .value after the parameter within the curly brackets, as shown in the following example: {customAttributes_COMPANY_Key_1.label}:{customAttributes_COMPANY_Key_1.value}. You need to manually add the colon (or any other symbol or text) if you want it to appear in the customer's email. You can drag and drop custom attributes into the cc/bcc lines of the notification template. For example, if key customer accounts have assigned account managers, their emails can be captured through a custom attribute and included in the cc/bcc line. This ensures account managers stay informed about all customer communications, helping them better manage expectations.

    Note: If you only click the parameter to add it to the template and do not specify the dot operator, the information displayed to the customer defaults to {customAttributes_COMPANY_Key_1.value}, and no label is displayed in the email.

14. (Optional) Configure the template to require the email recipient to enter a password to view the attached invoice. Click the Attachments drop-down list, select PDF invoice. This option is currently available only for the Invoice PDF Created notification. See Configure the PDF attachment policy for more information.

15. Click Create Template. A message confirms that the template was created and that its status is Disabled. Disabled notification templates are not evaluated by the notification system when it searches for a template to use for a notification.

16. (Optional) Click the Status toggle to change the status of the new template from Disabled to Enabled.

17. (Optional) Configure the template to be available in other languages so that the notification can be sent in the user's preferred language. To do this:

    1. Create a new version of the template using the preceding procedure.
    2. Open the new version, then select the language from the drop-down list.
    3. Enter the content details in that language.
    4. Click Save. The additional language is added.
    5. Repeat the process for additional languages.

18. (Optional) To assign a priority to the new template (if you have more than one version of the template), see Set notification template priority. You can only prioritize templates that have the Enabled status.

19. (Optional) To Manage the unsubscribe link that appears in the email footer, see Manage the unsubscribe feature.

To view the default content for each notification type, see Notification template content.