Configure adjustable notification plan

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

Introduction

In an adjustable notification plan, the API provider can adjust the target number of transactions for each app developer. You can configure if and when notifications are sent based on when a percentage of the target number is reached, such as 90%, 100%, or 150%. Additional transactions are not blocked after the target number is reached.

Configuring an adjustable notification plan using the UI

Configure adjustable notification plans, as described below.

Edge

To configure an adjustable notification plan using the Edge UI, when adding or editing a rate plan select Adjustable Notification rate plan type and in the Adjustable Notification section, configure the following information:

Field	Description	Default
Calculation frequency	Period of time over which the volume of transactions (or custom attribute-related volume) is calculated. Select a number of months (1-24 months).	1 month

If you defined custom attributes for your API product, you can configure a custom rating parameter to define a transaction counter based on a custom attribute.

For example, you may need to:

Charge developers a variable amount based on a value provided in the message of an API call.
For example, you may want to charge app developers based on the number of bytes transmitted in the API request.
Bundle multiple API calls into a single transaction.
In this case, select Use custom rating parameter and select the custom attribute from the drop-down list.

For more information, see Configure rate plan with custom attributes.

Classic Edge (Private Cloud)

To configure adjustable notification plans using the Classic Edge UI:

Select Adjustable Notification in the Rate Plan Type field on the Plan Details tab in the Rate Plan window.
See Creating a rate plan using the UI for information about accessing the Rate Plan window.

Note: The Fees and Freemium tabs will be grayed out after you select the Adjustable Notification type, as they are not applicable for adjustable notification plans.
Set the Renewal Term field to the number of months at which time the plan is automatically renewed (unless the developer terminates the agreement prior to that date). If you set this value to 0, the plan remains in effect until the developer chooses to end it.
Click Details under Generic Rate Plan.
Set the Aggregation Basis to the period of time over which the volume of transactions is aggregated. Select a number between 1 and 24 months. This value defaults to 1 month.
Click Apply and Close.
Click Save Draft.
Publish the plan only when you're absolutely sure it's final. See Publishing rate plans for information about setting the Publish Date and publishing the plan.

After you publish a rate plan, you can only modify the end date. You cannot delete a rate plan after it's published, but you can expire the rate plan and replace it with a future rate plan, as described in Expire a published rate plan.

Configuring an adjustable notification plan using the API

Specify the adjustable notification plan details in the ratePlanDetails property in the request body in a POST request to /organizations/{org_name}/monetization-packages/{package_id}/rate-plans.

To specify an adjustable notification plan, specify the following values in the ratePlanDetails of the request body:

Property	Value
`type`	Set to `USAGE_TARGET`.
`meteringType`	Set to `DEV_SPECIFIC`.
`duration`	Set to the period of time for the aggregation basis, together with `durationType`. For adjustable notification rate plans, set this to an integer value between 1 and 24.
`durationType`	Set to the period of time for the aggregation basis, together with `durationType`. For adjustable notification rate plans, set this value to `MONTH`.

For more information about the configuration properties that can be set when specifying adjustable notification plan details, see Rate plan details configuration settings.

For example, the following defines an adjustable notification plan with an aggregation basis set to 1 month.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "AdjustableNotification",
     "displayName": "Adjustable notification plan",
     "description": "Adjustable notification plan",
     "published": "true",  
     "organization": {
      "id": "myorg"
     },
     "startDate": "2016-04-15 00:00:00",
     "type": "STANDARD",
     "monetizationPackage": {
        "id": "p1",
        "name": "test"
     },
     "currency": {
        "id" : "usd",
        "name" : "USD"
     },
     "ratePlanDetails": [
        {
           "type": "USAGE_TARGET",
           "meteringType": "DEV_SPECIFIC",
           "duration": 1,
           "durationType": "MONTH",
           "ratingParameter": "VOLUME",
           "organization": {
             "id": "myorg"
           },
           "currency": {
             "id": "usd",
             "name": "USD"
           }
        }
     ]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans"  \
-u email:password

Setting the target number of transactions for each app developer using the API

For each app developer that has accepted the adjustable notification rate plan, you need to set the target number of transactions. You can configure if and when notifications are sent based on when a percentage of the target number is reached, such as 90%, 100%, or 150%. Additional transactions are not blocked after the target number is reached.

You can set the target number of transactions for an app developer when the developer accepts the rate plan, and you can update the value later.

Setting the target number of transactions when accepting the rate plan

When accepting the rate plan, to set the target number of transactions, specify the quotaTarget property in the request body in a POST request to the /organizations/{org_name}/developers/{developer_id}/developer-rateplans resource. Set quotaTarget to a positive integer or 0 to disable notifications for the app developer. If not specified, quotaTarget defaults to 0.

For example, the following request sets the target number of transactions to 4000 when the app developer accepts the adjustable notification plan.

$ curl -H "Content-Type:application/json" -X POST -d \
'{ 
   "developer":{
     "id":"dev@mycompany.org"
   },
   "ratePlan":{
     "id":"p1_adjustable-notification-plan"
   },
   "startDate": "2016-03-24 00:00:00",
   "quotaTarget": 4000,
   "suppressWarning": false
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/developer-rateplans" \
-u email:password

Setting the target number of transactions when updating the accepted rate plan

To set the target number of transactions, you can update the accepted rate plan and specify the quotaTarget property in the request body in a PUT request to the /organizations/{org_name}/developers/{developer_id}/developer-rateplans/{developer_rateplan_id} resource. Set quotaTarget to a positive integer or 0 to disable notifications for the app developer. If not specified, quotaTarget defaults to 0.

The {developer_rateplan_id} is returned in the response when you accept the published rate plan.

For example:

{
  "created": "2016-03-31 18:59:54",
  "developer": {
    ...
  },
  "id": "b1c600b8-f871-496d-8173-12b9950d6ab1",
  "quotaTarget": 3000,
  "ratePlan": {
    ...
  },
  "startDate": "2016-03-31 00:00:00",
  "updated": "2016-03-31 18:59:54",
  "waiveTerminationCharge": false
}

Alternatively, you can obtain the {developer-rateplan-id} for the developer rate plan by issuing a GET request to /organizations/{org_name}/developers/{developer_id}/developer-accepted-rateplans, where {developer_id} is the email address of the developer. For more information, see Viewing all rate plans accepted by a developer.

For example:

{
  "developerRatePlan": [
    {
      "created": "2016-03-31 14:52:30",
      "developer": {
        ...
      },
      "id": "b1c600b8-f871-496d-8173-12b9950d6ab1",
      "quotaTarget": 3000,
      "ratePlan": { 
        ... 
      }, 
      "startDate": "2016-03-31 00:00:00", 
      "updated": "2016-03-31 18:59:54" 
    } 
  ], 
  "totalRecords": 1 
}

The following request updates the target number of transactions to 4000.

$ curl -H "Content-Type:application/json" -X PUT -d \
'{ 
   "id" : "b1c600b8-f871-496d-8173-12b9950d6ab1",
   "developer":{
     "id":"dev@mycompany.com"
   },
   "ratePlan":{
     "id":"p1_adjustable-notification-plan"
   },
   "startDate": "2016-04-15 00:00:00",
   "quotaTarget": 4000,
   "suppressWarning":false
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/developer-rateplans/b1c600b8-f871-496d-8173-12b9950d6ab1"
-u email:password