Was this helpful?

Introduction

Monetization enables you to set up automatic notifications so that you can alert developers about events such as new products, new versions of T&C's, or new rate plans. You can also set up alerts notifying specific developers about events such as a billing document being published. In addition, as an API provider, you can be notified about developer-related events such as when a developer registers for an account or when a developer signs up for a rate plan.

You can also set up automatic notifications for limits so that a developer is alerted when a limit is approaching or is reached. You can set up these notifications using the management UI or monetization API. See Set up limit notifications for instructions on setting up limit notifications in the UI. If you use the API, you set up automatic notifications for limits in the same way as for other notifications and alerts, as described in this topic.

Toolbox

You can set up event notifications and alerts using the management UI or monetization API. If you use the UI, you set up event notifications and alerts on the Notifications page.

If you use the API, you set up event notifications and alerts by editing a notification template. You then specify the condition that results in sending the notification provided by the edited template.

Setting up event notifications and alerts using the UI

  1. On the Admin tab, select Notifications

    This opens the Notification page.

    The Notifications page displays three sections:

  2. Check one or more of the event checkboxes in each section (as appropriate) to open an area for you to set up notification for that event type. Clear checkboxes if you do not want to set up notifications for that event type.

    Notify All Developers

    Notifications for the types of events you select in the Notify All Developers section are sent to all developers. When you select an event type, the area expands to display Subject and Body fields where you can provide an email template specific to the event. The screenshot shown here provides a few examples of email templates using available template variables. For more information about available template variables, see Template variables.

    These notifications are scheduled to run at the end of the day. After the notifications have been sent, the event checkboxes are automatically cleared. You must select them again to schedule notifications for the event types again.

    The event types in the Notify All Developers section are as follows:

    Event Type Description
    New package

    A new API package is available. Add the name of each new package (and the products contained in each package) to the body of the email template as part of your update. You can also add a link to the developer portal or any other website that provides more information about the notification.

    New product

    A new API product is available. Add the name of each new product to the body of the email template as part of your update. You can also add a link to the developer portal or any other website that provides more information about the notification.

    New Markets/Coverage

    New API products are available in specific geographic markets. Add the name of each new market and pertinent products to the body of the email template as part of your update. You can also add a link to the developer portal or any other website that provides more information about the notification. (This type of notification is more common for group companies that launch an API product on one or more of subsidiaries based in other countries.)

    Notify Affected Developers

    Notifications for the types of events you select in the Notify Affected Developers section are sent to only the developers affected by those types of events. For example, if you select the Billing Document Published checkbox, a notification is sent only to the developer for whom the billing documents are published. When you select an event type, the area expands to display Subject and Body fields where you can provide an email template specific to the event. The screenshot shown here provides a few examples of email templates using available template variables. For more information about available template variables, see Template variables.

    These notifications are automatic and are based on the occurrence of the events. If you want to stop the notifications for an event, you must clear its checkbox. 

    Notify Affected Developers section

    The event types in the Notify Affected Developers section are as follows:

    Event Type Description
    T&C not accepted or expired

    These notifications are applicable when you have published a new set of T&Cs, and the developer has not yet accepted them. The notification is sent 30 days, 7 days, and 1 day before the new T&Cs are due to go into effect.

    New rate plan

    These notifications are applicable when you publish a new rate plan. If the rate plan is a standard plan, all developers will get notified. If it is a developer category rate plan, only developers in that category will get notified. If it is a developer rate plan, only that specific developer will get notified.

    Revised rate plan

    A newer version of a purchased rate plan is available. Only those developers who purchased the current version will be notified. This allows those developers to review the newer version and choose to terminate or switch plans if they do not accept the new rates.

    Expired Rate plan

    Use this notification to alert affected developers when you have chosen to expire a rate plan with no follow-up rate plan. This notification is sent when you initially set the rate plan to expire, with additional notifications sent 30, 7, and 1 day before the expiration date. Only those developers who have purchased the rate plan to be expired will be notified.

    Renewed Rate Plan

    Use this notification to alert affected developers that a rate plan subscription has been renewed and that any applicable fees will be charged.

    Depleted Freemium Rate Plan

    Use this notification to alert affected developers that their free usage periods, measured by transaction count or days, have been depleted. The free usage period is defined by your freemium rate plan.

    Billing Document published

    Billing documents (such as invoices) for the developer are available.

    Developer signs up for new Rate Plan

    Use this notification to send an alert to affected developers confirming that they have signed up for a rate plan.

    Notify API Provider

    Notifications for the types of events you select in the Notify API Provider section are sent to the API provider you specify. When you select an event type, the area expands to display Subject and Body fields where you can provide an email template specific to the event. The screenshot shown here provides a few examples of email templates using available template variables. For more information about available template variables, see Template variables.

    These notifications are automatic and are based on the occurrence of the events. If you want to stop the notifications for an event, you must clear its checkbox.

    The event types in the Notify API Provider section are as follows:

    Event Type Description
    New Developer Signs Up

    A developer has registered for an account.

    Developer Adds an App

    A developer has created a new application.

    Developer Sign Up for New Rate Plan

    A developer has signed up for a rate plan.

    Developer changes financial details

    A developer has changed financial details such as his company name or company address..

  3. Click Update Notifications to save your notification settings.

    After you click Update Notifications, the system disables the update button and displays a message to confirm that the notifications have been saved. This may take a few minutes.

Updating event notifications and alerts using the UI

  1. On the Admin tab, select Notifications to open the Notifications page.
  2. Check the checkboxes for the pertinent event types to open their areas on the page.
  3. Update the Subject, Body, and To fields, as needed, for each event type you check.
  4. Click Update Notifications to save your notification updates.

Removing event notifications and alerts using the UI

  1. On the Admin tab, select Notifications to open the Notifications page.
  2. Clear the checkboxes for the pertinent event types that you want to remove.
  3. Click Update Notifications to save your notification updates.

Setting up event notifications and alerts using the API

Monetization provides a set of templates that provides the text for various types of notifications, including limit notifications as well as ad-hoc notifications. You can tailor any of these templates to meet your needs. To set up a notification, first edit an appropriate template. Then specify the condition that results in sending the notification provided by the edited template.

Working with notification templates

The notification templates are provided by the Notifications resource. The resource path to the templates is notification/organizations/{org_name}/emailtemplates. You can list all the notification templates that monetization provides by issuing a GET request to that resource path. For example:

    $ curl -H "Accept:application/json" -X GET \
    "https://api.enterprise.apigee.com/v1/notification/organizations/{org_name}/emailtemplates" \
    -u myname:mypass

You’ll notice that some of the templates are designed for ad-hoc notifications and some for limit notifications. For example, the following is an ad-hoc template that notifies developers of the availability of a new API product:

    {
    "createdDate" : 1376975394984,
    "htmlImage" : "<p>Dear ${developer.legalName} , ${developer.name} <br /> Introducing _________. For more details visit us at _________________</p>",
    "id" : "4d81ea64-d005-4010-b0a7-6ec8a5c3954b",
    "name" : "DEFAULT_NEW_PRODUCT_TEMPLATE",
    "orgId" : "myorg",
    "source" : "Mail Man Test",
    "subject" : "Notification of new product",
    "updatedDate" : 1376975394984
    }

The following template is designed to notify developers when they have reached a limit and that their API calls will be blocked until an expiration date:

    {
    "createdDate" : 1376975468114,
    "htmlImage" : "<p>Dear ${developer.legalName} , ${developer.name} <br />You have exceeded ${QUOTA_TYPE} of ${PERCENT} ${QUOTA_UNIT} of ${QUOTA_LIMIT} ${QUOTA_UNIT} for ${ratePlan.monetizationPackage.name} package, ${ratePlan.monetizationPackage.products.name} product. Your API calls will be blocked till ${EXPIRY_DATE}</p>",
    "id" : "3cce3dac-af0d-415e-b00a-a65a8d37d3ab",
    "name" : "DEFAULT_DEVELOPER_HALT_LIMIT_TEMPLATE",
    "orgId" : "{org_name}",
    "source" : "Mail Man Test",
    "subject" : "Limit notification",
    "updatedDate" : 1376975468114
    }

You can retrieve a specific notification template by issuing a GET request to notification/organizations/{org_name}/emailtemplates/{template_id}, where {template_id} is the identification of the template. For example:

    $ curl -H "Accept:application/json" -X GET \
    "https://api.enterprise.apigee.com/v1/notification/organizations/{org_name}/emailtemplates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b" \
    -u myname:mypass

The items in the templates that begin with $ are variables (see Template variables for descriptions). Assume that the values of the variables in the limit notification are as follows:

  • ${developer.legalName}.XYZ company
  • ${developer.name}.DEV1
  • ${QUOTA_TYPE}.Transactions
  • ${PERCENT}.90%
  • ${QUOTA_UNIT}.Calls
  • ${QUOTA_LIMIT}.100
  • ${ratePlan.monetizationPackage.products.name}.X
  • ${EXPIRY_DATE}.2013-09-30

The notification message provided by the template would look like this:

    "Dear XYZ company, DEV1
    You have exceeded Transactions of 90% calls of 100 calls for X product. Your API calls will be blocked till 2013-09-30"

You can edit a template by issuing a POST request to notification/organizations/{org_name}/emailtemplates/{template_id}. Provide the updated content of the template in the request body. For example, the following request updates the content of a new API product notification:

    $ curl -H "Content-Type: application/json" -X PUT -d \
    '{
    "id" : "4d81ea64-d005-4010-b0a7-6ec8a5c3954b",
    "htmlImage" : "<p>Exciting news, we have added a new product :${Product.name}. See details in <a href="${Product.url}">New Products</a> </p>",
    "name" : "NewProductNotification",
    "organization": {
    "id": "{org_name}"
    },
    "source" : "Mail Man Test ",
    "subject" : "New Product Available: ${Product.name}"
    }' \
    "https://api.enterprise.apigee.com/v1/notification/organizations/{org_name}/emailtemplates/4d81ea64-d005-4010-b0a7-6ec8a5c3954b " \
    -u myname:mypass

The following request updates the content of a limit notification.

    $ curl -H "Content-Type: application/json" -X PUT -d \
    '{
    "id" : "curl -H "Content-Type: application/json" -X PUT -d \
    '{
    "id" : "82b8cbe3-5c78-4d7d-b857-b46a2c5484ee",
    "htmlImage" : "<p>You have reached ${percentage} of your transaction volume limit of ${QUOTA_LIMIT} transactions.</p>",
    "name" : "DEFAULT_PROVIDER_HALT_LIMIT_TEMPLATE",
    "organization": {
    "id": "{org_name}"
    },
    "source" : "Mail Man Test",
    "subject" : "Limit notification"
    }' \
    "https://api.enterprise.apigee.com/v1/notification/organizations/scm/emailtemplates/82b8cbe3-5c78-4d7d-b857-b46a2c5484ee" \
    -u admin@apix.com:apigee123 -k",

Template variables

When you edit the message in a notification template, you can include any of the following variables.

Variable Description
${application.name}

Name of an application.

${application.products.name} Name of a product included in an application.
${BALANCE} Balance for a given quota.
${calendarMonth} Month for which billing documents have been made available.
${developer.legalName}

Name of a developer’s company.

${developer.name}

Name of a developer.

${developerRatePlan.startDate} Effective start date accepted by a developer
${errorDesc} Description of the reason why a developer's recurring payments enrollment failed.
${EXPIRY_DATE}

Date or time at which a limit expires or gets reset.

${PERCENT}

Percentage of a limit reached by current usage.

${products.displayName} Display name defined for a product.
${Product.name}

Name of a product.

${Product.url}

URL of a product.

${QUOTA_TYPE}

Type of limit (transaction volume, spend limit, or fee exposure).

${QUOTA_UNIT}

Basic unit for a limit: currency (for a spend limit), or calls (for a transaction limit).

${QUOTA_LIMIT}

Amount of a limit.

${ratePlan.displayName} Display name defined for a rate plan.
${ratePlan.endDate} Date on which an API provider ended a rate plan.
${ratePlan.monetizationPackage.displayName}

Name of an API package.

${ratePlan.monetizationPackage.name} Name of a Monetization package.
${ratePlan.monetizationPackage.products.displayName}

Display name defined for an API product.

${ratePlan.monetizationPackage.products.name} Name of a product included in a Monetization package.
${ratePlan.startDate} Date on which a rate plan was created.
${termAndCondition.startDate} Date on which Terms and Conditions provided by an API provider go into effect.
${USAGE} Current usage (total revenue or charges, or volume).
${USER}

Name of a user.

Specifying a notification condition and action using the API

To specify a condition that results in an automatic notification to everyone in the organization , issue a POST request to /organizations/{org_name}/notification-conditions. When you make the request, specify in the request body the condition that results in the notification, and actions to be taken when the condition is reached (such as sending a notification email).

You can also notify a specific developer when a condition is reached. To do that, issue a POST request to /organizations/{org_name}/developers/{developer_Id}/notification-conditions, where {developer_Id is the identification of the developer. When you make the request, specify in the request body the condition that results in the notification, and actions to be taken when the condition is reached (such as sending a notification email).

You specify the condition through applicable attributes (see Notification condition configuration settings for a list of attributes). For an ad-hoc notification, the condition could be the publishing of a new product. For a limit notification, the condition could be that a threshold value is reached (such as 90% of the transaction limit).

In the actions, point to the applicable notification template (see Notification action configuration settings for a list of actions).

For example, the following request specifies that when the attribute is NEW_PRODUCT and the value of the attribute PUBLISHED is true, send the notification in the template whose ID is 01191bf9-5fdd-45bf-8130-3f024694e63 (this is the DEFAULT_NEW_PRODUCT_TEMPLATE).

    $ curl -H "Content-Type:application/json" -X POST -d \
    ' {
    "notificationCondition": [
    {
    "name": "CreateProduct",
    "attribute": "NEW_PRODUCT"
    },
    {
    "attribute": "PUBLISHED",
    "value": "true"
    }
    ],
    "actions": [{
    "actionAttribute": "DEV_ID",
    "value": "ANY",
    "templateId": "01191bf9-5fdd-45bf-8130-3f024694e63"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions" \
    -u myname:mypass

The following request specifies that when 90% of the applicable limit is reached, send an email notification using the notification template whose ID is 5320bcce-19ad-4912-aefc-701606a09ef3 (this is the DEFAULT_DEVELOPER_WARNING_LIMIT_TEMPLATE).

    $ curl -H "Content-Type:application/json" -X POST -d \
    
    '{
    "notificationCondition": [
    {
    "limit": { "id": "e2756f13-724b-4924-ab04-6aa22c60efea" },
    "value": "> 90 %"
    }
    ],
    "actions": [{
    "actionAttribute": "DEV_ID",
    "value": "ANY",
    "templateId": "5320bcce-19ad-4912-aefc-701606a09ef3"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/notification-conditions" \
    -u myname:mypass

The following request send the same notification when 90% of the applicable limit is reached, but sends it only to the developer whose ID is a4544b3c-5cfe-4ff8-ac6c-2ccceb16b265.

    $ curl -H "Content-Type:application/json" -X POST -d \
    
    '{
    "notificationCondition": [
    {
    "limit": { "id": "e2756f13-724b-4924-ab04-6aa22c60efea" },
    "value": "> 90 %"
    }
    ],
    "actions": [{
    "actionAttribute": "DEV_ID",
    "value": "5cTWgdUvdr6JW3xU",
    "templateId": "5320bcce-19ad-4912-aefc-701606a09ef3"
    }]
    }' \
    "https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/notification-conditions" \
    -u myname:mypass

Retrieving a notification condition using the API

You can retrieve a notification by issuing a GET request to organizations/{org_name}notification-conditions/{condition_Id}, where {condition_Id} is the identification of the condition. The identification is returned when you created the notification condition. For example:

    $ curl -H "Accept:application/json" -X GET \
    "https://api.enterprise.apigee.com /v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4" \
    -u myname:mypass

The response should look something like this (only part of the response is shown):

    {
    "actions" : [ {
    "actionAttribute" : "DEV_ID",
    "id" : "141ba00c-d7bd-4fef-b339-9d58b83255f4",
    "templateId" : "766aba4f-0f7a-4555-b48e-d707c48b8f4c",
    "value" : "ANY"
    }, {
    "actionAttribute" : "ORG_EMAIL",
    "id" : "21486ce1-4290-4a55-b415-165af3e93c9d",
    "templateId" : "efa4ce63-7c08-4876-984b-6878ec435994",
    "value" : "DEFAULT_LIMIT_NOTIFICATION_EMAIL"
    } ],
    "notificationCondition" : [ {
    "attribute" : "Balance",
    "id" : "2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4",
    "organization" : {
    ...
    },
    "value" : "< 0"
    } ]
    }

Deleting a notification condition using the API

You can delete a notification condition by issuing a DELETE request to organizations/{org_name}notification-conditions/{condition_Id}. For example:

    $ curl -H "Accept:application/json" -X DELETE \
    "https://api.enterprise.apigee.com /v1/mint/organizations/{org_name}/notification-conditions/2d08d03f-8a54-4e75-bd6f-9c9da2f53fc4"  \
    -u myname:mypass

Notification condition configuration settings

The following notification condition configuration options are exposed to the API:

Name Description Default Required?
name

The name of the notification condition.

N/A No
limit

The identification of the limit.

N/A No
attribute

The type of event for which the notification is sent. The value can be one or more of the following:

  • LIMIT_ID
  • ORG_ID
  • DEV_ID
  • APP_ID
  • VOLUME
  • PUBLISHED
  • DATE
  • Transactions
  • CreditLimit
  • SpendLimit
  • FeeExposure
  • Balance
  • CREATE_DEVELOPER
  • UPDATE_DEVELOPER
  • CREATE_APPLICATION
  • NEW_PRODUCT
  • NEW_PACKAGE
  • ADHOC_NOTIFY_DEVELOPERS
  • ADD_RATEPLAN
  • RATEPLAN_ACCEPTED
  • RATEPLAN_REVISION
  • RATEPLAN_ENDED
  • NEW_TNC
  • TNC_ACCEPTANCE
  • EXPIRING_TNC
  • BILLING_DOCS_PUBLISHED
  • RATEDPLAN_EXPIRED
  • RATEPLAN_RENEWED
  • FREEMIUM_USED_UP
N/A Yes
value

The value of the attribute.

N/A No
associatedCondition

A reference to an associated condition.

N/A No

Notification action configuration settings

The following configuration options are available for notification actions:

Name Description Default Required?
actionAttribute

How the notification recipient is identified. The value can be one or more of the following:

  • ORG_EMAIL. The notification recipient is identified by email address.
  • DEV_ID. The notification recipient is identified by developer ID.

 

N/A Yes
value

The value of the action attribute. A value of ANY means send the notification to any applicable recipient, for example, any ORG_EMAIL address or any DEV_ID.

N/A Yes
templateID

The identification of the notification template.

N/A Yes

Get help

For help, see Apigee Customer Support.

Next steps

Using monetization you can create developer categories. This enables you to create a rate plan that applies specifically to a category. Learn how in Manage developers.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)