Skip to main content

Use Cases of Usage Threshold Notifications

Zuora

Use Cases of Usage Threshold Notifications

  1. Last updated
  2. Save as PDF

The Usage Threshold Notifications feature in Limited Availability. If you wish to have access to the feature, submit a request at Zuora Global Support.

This article introduces some common use cases of the Usage Threshold Notifications feature.

Case I: Configure Usage Percentage Threshold Notifications at the Tenant Level 

You want to ensure that email notifications will be triggered when the consumed usage reaches the specified threshold of the total usage amount at the tenant level. For example, you can notify your sales team about a customer usage threshold so that they can explore upsale opportunities

In this case, notifications will be triggered and sent to all users subscribing to every charge with an eligible charge model in the tenant.

  1. Create an email template through the REST API, and note down the returned email template ID.

    The following is an example HTTP/JSON request.

    POST https://rest.zuora.com/notifications/email-templates

    {
   "active": true,
   "bccEmailAddress": "",
   "ccEmailAddress": "",
   "ccEmailType": "SpecificEmails",
   "description": "Email notifications when the consumed usage reaches or exceeds the usage percentage threshold.",
   "emailBody": "Dear User,<p>Your account has exceeded the usage percentage threshold limit. The current usage is <UsageThresholdEvent.CurrentUsageQuantity> (<UsageThresholdEvent.CurrentUsagePercentage>) <\/p><p>Thank you.<\/p> <\/p><p>Example Co., Ltd.<\/p>",
   "emailSubject": "Account usage threshold exceeded",
   "encodingType": "UTF8",
   "eventTypeName": "UsageThresholdEvent",
   "fromEmailAddress": "example@example.com",
   "fromEmailType": "TenantEmail",
   "fromName": "Example Co., Ltd.",
   "isHtml": true,
   "name": "Account Usage Percentage Threshold Reached",
   "replyToEmailAddress": null,
   "replyToEmailType": "TenantEmail",
   "toEmailAddress": "contact1@example.com",
   "toEmailType": "BillToContact"
}

    The following is an example JSON response of the preceding request. Note down the email template ID 9b6e120b3d3e4ff887e57540f8f308af to be used when you create a notification definition.

    {
    "id": "9b6e120b3d3e4ff887e57540f8f308af",
    "createdBy": "2c92c0f8643b6a5d016444164d2242c3",
    "createdOn": "2018-08-31T08:24:35.819 UTC",
    "updatedBy": "2c92c0f8643b6a5d016444164d2242c3",
    "updatedOn": "2018-08-31T08:24:35.819 UTC",
    "eventTypeName": "UsageThresholdEvent",
    "name": "Account Usage Percentage Threshold Reached",
    "description": "Email notifications when the consumed usage reaches or exceeds the usage percentage threshold.",
    "encodingType": "UTF8",
    "fromName": "Example Co., Ltd.",
    "fromEmailType": "TenantEmail",
    "fromEmailAddress": "example@example.com",
    "replyToEmailType": "TenantEmail",
    "replyToEmailAddress": null,
    "ccEmailType": "SpecificEmails",
    "ccEmailAddress": "",
    "bccEmailAddress": "",
    "toEmailType": "BillToContact",
    "toEmailAddress": "contact1@example.com",
    "emailSubject": "Account usage threshold exceeded",
    "emailBody": "Dear User,<p>Your account has exceeded the usage percentage threshold limit. The current usage is <UsageThresholdEvent.CurrentUsageQuantity> (<UsageThresholdEvent.CurrentUsagePercentage>) </p><p>Thank you.</p> </p><p>Example Co., Ltd.</p>",
    "active": true,
    "isHtml": true
}
  2. Create a notification definition through the REST API.
    The email template ID and UsageThresholdEvent event type are used in this step.

    The following is an example HTTP/JSON request.

    POST https://rest.zuora.com/notifications/notification-definitions

    {
   "active": true,
   "emailActive": true,
   "emailTemplateId": "9b6e120b3d3e4ff887e57540f8f308af",
   "eventTypeName": "UsageThresholdEvent",
   "filterRule": {
      "condition": "_THRESHOLD_PERCENTAGE_1 >= 0 && UsageThresholdEvent.PreviousUsagePercentage < _THRESHOLD_PERCENTAGE_1 && UsageThresholdEvent.CurrentUsagePercentage >= _THRESHOLD_PERCENTAGE_1",
      "description": "Filter rule to test whether the current usage percentage has been exceeded the threshold.",
      "parameters": {
         "_THRESHOLD_PERCENTAGE_1": {
            "displayName": "Threshold percentage of notification 1",
            "description": "string",
            "valueType": "DOUBLE"
         }
      }
   },
   "filterRuleParams": {
      "_THRESHOLD_PERCENTAGE_1": "80"
   },
   "name": "Usage Threshold Tenant Level Notification"
}

    The percentage threshold value 80 and the values of the eventTypeName, displayName, and name fields in the preceding code sample will be displayed on the Zuora user interface after the notification definition is created. You can use the Zuora user interface to modify the threshold value that makes it easier for configuration later. 

  3. After the notification definition is created, you can update the usage percentage threshold through the Zuora user interface or by calling the "Update a notification definition" operation.
    The following picture depicts the Edit Notification dialog where you can update the notification definition.
    EditTenantLevelUsageThresholdNotificationDefinition.png
    You can specify a new value for the Threshold percentage of notification 1 field to update the usage percentage threshold. For example, if you change 80 to 90 for this field, the usage percentage threshold becomes 90%.

Case II: Mute Usage Threshold Notifications for Customers

After you configure Usage Threshold Notifications at the tenant level, the configurations apply to all customers in the tenant. If you want to do not want to send notifications to a specific customer, you can mute notifications to the customer.

  1. Define a communication profile where usage threshold notifications are deactivated.
  2. Associate the communication profile with the specific customer account. 

Case III: Configure Usage Percentage Threshold Notifications at the Charge Level 

You want to ensure that your customers subscribing to a specific subscription rate plan charge can receive email notifications when they have consumed 50% of their total usage amount. In this context, you can configure usage percentage threshold notifications at the charge level. 

In this case, notifications will be triggered and sent to only specific users associated with the corresponding eligible subscription rate plan charge.

  1. Create a custom field for the Subscription Rate Plan Charge object.
    For example, you create a picklist custom field called threshold, with possible values of 50, 80, and 90. The default value 50 is used.
  2. Create an email template through the REST API, and note down the returned email template ID.

    The following is an example HTTP/JSON request.

    POST https://rest.zuora.com/notifications/email-templates

    {
   "active": true,
   "bccEmailAddress": "",
   "ccEmailAddress": "",
   "ccEmailType": "SpecificEmails",
   "description": "Email notifications when the consumed usage reaches or exceeds the usage percentage threshold at the charge level.",
   "emailBody": "Dear User,<p>Your charge has exceeded the usage percentage threshold limit. The current usage is <UsageThresholdEvent.CurrentUsageQuantity> (<UsageThresholdEvent.CurrentUsagePercentage>) <\/p><p>Thank you.<\/p> <\/p><p>Example Co., Ltd.<\/p>",
   "emailSubject": "Charge usage threshold exceeded",
   "encodingType": "UTF8",
   "eventTypeName": "UsageThresholdCustomFieldEvent",
   "fromEmailAddress": "example@example.com",
   "fromEmailType": "TenantEmail",
   "fromName": "Example Co., Ltd.",
   "isHtml": true,
   "name": "Charge Usage Percentage Threshold Reached",
   "replyToEmailAddress": null,
   "replyToEmailType": "TenantEmail",
   "toEmailAddress": "contact2@example.com",
   "toEmailType": "BillToContact"
}

    The following is an example JSON response of the preceding request. Note down the email template ID 6f581a4c1d6f48258a6ed37a39abd9a6 to be used when you create a notification definition.

    {
    "id": "6f581a4c1d6f48258a6ed37a39abd9a6",
    "createdBy": "2c92c0f8643b6a5d016444164d2242c3",
    "createdOn": "2018-08-31T08:27:29.334 UTC",
    "updatedBy": "2c92c0f8643b6a5d016444164d2242c3",
    "updatedOn": "2018-08-31T08:27:29.334 UTC",
    "eventTypeName": "UsageThresholdCustomFieldEvent",
    "name": "Charge Usage Percentage Threshold Reached",
    "description": "Email notifications when the consumed usage reaches or exceeds the usage percentage threshold at the charge level.",
    "encodingType": "UTF8",
    "fromName": "Example Co., Ltd.",
    "fromEmailType": "TenantEmail",
    "fromEmailAddress": "example@example.com",
    "replyToEmailType": "TenantEmail",
    "replyToEmailAddress": null,
    "ccEmailType": "SpecificEmails",
    "ccEmailAddress": "",
    "bccEmailAddress": "",
    "toEmailType": "BillToContact",
    "toEmailAddress": "contact2@example.com",
    "emailSubject": "Charge usage threshold exceeded",
    "emailBody": "Dear User,<p>Your charge has exceeded the usage percentage threshold limit. The current usage is <UsageThresholdEvent.CurrentUsageQuantity> (<UsageThresholdEvent.CurrentUsagePercentage>) </p><p>Thank you.</p> </p><p>Example Co., Ltd.</p>",
    "active": true,
    "isHtml": true
}
  3. Create a notification definition through the REST API.
    The email template ID, UsageThresholdCustomFieldEvent event type, and created custom field threshold are used in this step.

    The following is an example HTTP/JSON request.

    POST https://rest.zuora.com/notifications/notification-definitions

    {
   "active": true,
   "emailActive": true,
   "emailTemplateId": "6e569e1e05f040eda51a927b140c0ac2",
   "eventTypeName": "UsageThresholdCustomFieldEvent",
   "filterRule": {
      "condition": "RatePlanCharge.threshold__c>=0 && UsageThresholdEvent.CurrentUsagePercentage >= RatePlanCharge.threshold__c && UsageThresholdEvent.PreviousUsagePercentage < RatePlanCharge.threshold__c",
      "description": "Filter rule to test current usage percentage has been exceeded.",
      "parameters": {}
   }
}
  4. After the notification definition is created, you can update it through the Zuora user interface or by calling the "Update a notification definition" operation.
    The following picture depicts the Edit Notification dialog where you can update the notification definition. You cannot update the usage percentage threshold in this dialog.
    EditChargeLevelUsageThresholdNotificationDefinition.png
  5. To update the usage percentage threshold, update the value of the custom field threshold in the subscription rate plan charge through the Zuora user interface.
    1. On the subscription details page, click the charge name in the Product & Charges area.
    2. On the expanded charge details page, click Edit Custom Fields next to the custom field threshold.
    3. Change the value from the drop-down list for the threshold field, and click save. For example, if you change 50 to 80 for this field, the usage percentage threshold becomes 80%.
    4. Click done to save the subscription rate plan charge.