Send Docs Feedback

Create rate plans

Introduction

A rate plan specifies the monetization approach for your API package or for individual API products in the package. For example, it specifies whether you charge for the use of your API package and products based on a flat rate or a variable rate, and whether there are additional fees.

Developers can register their apps to use an API package only by purchasing one of the rate plans currently in effect. If an API package doesn't have a published rate plan that is currently in effect, the package isn't monetized.

You can set up multiple rate plans for an API package.

When you create a plan, you can configure the following options:

  • Specify the scope of the rate plan so that it is available to all developers or only a specific developer or developer category. See Understanding rate plan scopes.
  • Set the rate plan as public or private. See Public versus private rate plans.
  • Configure a revenue model. For example, you can configure a revenue share plan to share a percentage of the revenue generated from each transaction with the developer; a rate card plan, where you charge developers a flat rate or a variable rate for each transaction; or a revenue share and rate card plan which is a combination of the two. In addition, if you specify custom attributes in the Transaction Recording policy, you can set up a rate card plan based on custom attributes. For example, if you set up a rate card plan where you charge the developer for each transaction, you can set the rate for the plan based on a custom attribute such as the number of bytes transmitted in a transaction. See Specify rate plan details.
  • Set a one-time or recurring fee for the plan. See Add fees to a rate plan.
  • Add a "freemium" part to the plan, where you offer developers free use of the products in an API package over a period of time or based on the amount of use. See Add a freemium plan.
  • Set a renewal period (in months or years). Monetization automatically renews the plan after the renewal period expires (unless the developer terminates the agreement prior to that date). You can choose not to set a renewal period, in which case, the plan remains in effect until the developer chooses to end it.
  • For API packages that include multiple products, you can make the plan generic (that is, it applies to all the products in an API package), or product-specific.

After you create a rate plan, you can publish the plan or save it as a draft (see Publish rate plans). Publish it only when you're absolutely sure it's final. After you publish you can only modify the end date; you cannot delete a published rate plan.

After you publish a rate plan, you can perform one or more of the following task, as necessary:

Understanding rate plan scopes

When creating a rate plan, you configure one of the following scopes so that it is available to all developers, or only to a specific developer or developer category. 

Rate Plan Scope Applies to Description
Standard rate plan All developers After you create and publish the rate plan, all developers will be able to see it (and the API package) listed in the catalog in the Edge Developer Services developer portal, starting on the effective date of the plan.
Developer rate plan Specific developer After you create and publish the rate plan, the developer will be able to see it (and the package) listed in the catalog in the Edge Developer Services developer portal, starting on the effective date of the plan.
Developer category rate plan Developers in a selected category You can create a developer category rate plan only if developer categories have been previously created. See Manage developer categories for instructions on how to create developer categories.

After you create and publish the rate plan, all developers in that category are able to see it (and the API package) listed in the catalog in the Edge Developer Services developer portal, starting on the effective date of the plan.

Initially, no developers are assigned to the developer categories. After the developer categories are created, you can assign each developer to a pertinent category. See Manage developer categories for further details.

 

Public versus private rate plans

When creating a rate plan, you can specify whether it is public or private.

Type Description
Public Public rate plans are visible to app developers in the Developer Service Portal. App developers can self-subscribe to the rate plan.
Private Private rate plans are not visible to app developers in the Developer Service Portal. You must manually purchase the rate plan on behalf of the app developer using the management UI or monetization API. Once purchased, the app developer will see the rate plan in the list of purchased rate plans.

Toolbox

You can create rate plans using the Edge management UI or monetization API.

  • To use the UI, you create a rate plan by selecting a package in the package catalog and then clicking + Add Rate Plan.
  • To use the API, you create a rate plan by issuing a POST request to the /organizations/{org_name}/monetization-packages/{package_id}/rate-plans resource. After you create rate plans, you can manage your rate plans using the /organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{plan_id} resource.

Creating rate plans using the UI

Using the UI, create a rate plan with one of the following scopes:

For more information, about rate plan scopes, see Understanding rate plan scopes.

Creating a standard rate plan using the UI

A standard rate plan applies to all developers. For more information about rate plan scopes, see Understanding rate plan scopes.

To create a standard rate plan:

  1. Click +Add Rate Plan next to the associated API package in the package catalog.

    This opens the Rate Plan window.

    Rate plan dialog

  2. Select Standard from the Standard or Developer drop-down menu.
  3. Enter a name for the plan in the Rate Plan Name field.

    The name must be unique within an API package. Two plans in the same package cannot have the same name.

  4. Specify whether the rate plan is public or private by selecting a value in the Access field. For more information, see Public versus private rate plans.
  5. Add fees to a rate plan (optional).
  6. Add a freemium plan (optional).
  7. Specify rate plan details (optional).
  8. Click Save Draft.
  9. Publish the plan only when you're absolutely sure it's final. See Publish 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 Expiring a published rate plan.

Creating a developer rate plan using the UI

A developer rate plan applies to a specific developer. For more information about rate plan scopes, see Understanding rate plan scopes.

To create a developer rate plan:

  1. Click +Add Rate Plan next to the associated API package in the package catalog to open the Rate Plan window.
  2. Select Developer from the Standard or Developer drop-down menu.

    The Developer selection is available only if developers are registered in your organization and the registration includes the developer’s company name. Developers can register themselves through a developer portal or you can register them using the management UI or Edge API Services APIs. For instructions on registering developers, see "Adding a Developer" in Adding developers to your organization.

  3. Select a developer from the developer drop-down menu.

  4. Enter a name for the plan in the Rate Plan Name field.

    The name must be unique within an API package. Two plans in the same package cannot have the same name.

  5. Specify whether the rate plan is public or private by selecting a value in the Access field. For more information, see Public versus private rate plans.
  6. Add fees to a rate plan (optional).
  7. Add a freemium plan (optional).
  8. Specify rate plan details (optional).
  9. Click Save Draft.
  10. Publish the plan only when you're absolutely sure it's final. See Publish 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 Expiring a published rate plan.

Creating a developer category rate plan using the UI

A developer category rate plan applies to all developers in a selected category. For more information about rate plan scopes, see Understanding rate plan scopes.

To create a developer category rate plan:

  1. Click +Add Rate Plan next to the associated API package in the package catalog to open the Rate Plan window.
  2. Select Developer Category from the Standard or Developer drop-down menu.

    The Developer Category selection is available only if developer categories have been created.

  3. Select a developer category from the developer category drop-down menu.
  4. Enter a name for the plan in the Rate Plan Name field.

    The name must be unique within an API package. Two plans in the same package cannot have the same name.

  5. Specify whether the rate plan is public or private by selecting a value in the Access field. For more information, see Public versus private rate plans.
  6. Add fees to a rate plan (optional).
  7. Add a freemium plan (optional).
  8. Specify rate plan details (optional).
  9. Click Save Draft.
  10. Publish the plan only when you're absolutely sure it's final. See Publish 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 Expiring a published rate plan.

Setting the rate plan as public or private using the UI

When creating the rate plan, you specify whether the rate plan is public or private by selecting a value in the Access field. By default, rate plans are public.

After you create a rate plan, you can change the access setting by performing the following tasks:

  1. On the Publish tab, select Packages to open the API package catalog.

  2. Click the Packaged Rate Plans tab (if it is not already selected).
  3. In the Access column of the rate plan you want to edit, click the Private or Public label to toggle the access setting.

For more information about public and private rate plans, see Public versus private rate plans.

Creating rate plans using the API

To create a rate plan, issue a POST request to /organizations/{org_name}/monetization-packages/{monetizationpackage_id}/rate-plans, where {monetizationpackage_id} is the ID of the API package for which you create the rate plan (the ID is returned in the response when you create the API package).

When you create a rate plan, you must specify the following in the request body:

  • Organization ID
  • API package ID
  • Name of the rate plan
  • Description of the rate plan
  • Scope of the rate plan (whether it applies to all developers, or only to a specific developer or category)
  • Date when the rate plan goes into effect
  • Currency for the rate plan
  • Whether to publish the rate plan
  • Whether the rate plan is public or private

There are other settings that you can optionally specify, such as the period when payment is due (for example, 30 days). See Configuration settings for rate plans for a complete list of rate plan options.

If you create a rate plan (other than a fees only plan) for an API package that has more than one product, you can apply the plan to a specific product in the package. You do this by identifying the product in the request. If you don’t identify a product, the plan is applied to all products in the API package.

Creating a standard rate plan using the API

To create a standard rate plan, set the type attribute to STANDARD, as shown in the following example.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Simple rate plan",
     "currency": {
      "id" : "usd"
     },
     "description": "Simple rate plan",
     "displayName" : "Simple rate plan",     
     "monetizationPackage": {
      "id": "location"
     },
     "organization": {
      "id": "{org_name}"
     },     
     "published": true,
     "isPrivate" : false,
     "ratePlanDetails": [
     {
      …            
     }
     ],
     "startDate": "2013-09-15",
     "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location_package/rate-plans" \
-u email:password

Creating a developer rate plan using the API

To apply the rate plan to a specific developer, set the type value to Developer. You also need to identify the developer in the request. For example:

...
     "type": "DEVELOPER",
       "developer" : {    
        "id" : "0mkKu1PALUGfjUph",
        "legalName" : "DEV FIVE",
        "name" : "Dev Five"
      }  
... 

Creating a developer category rate plan using the API

To apply the rate plan to a developer category, set the type value to Developer_Category. You also need to identify the developer category in the request. For example:

...
     "type": "DEVELOPER_CATEGORY",
       "developerCategory" : {    
        "id" : "5e172299-8232-45f9-ac46-40076139f373",
        "name" : "Silver",
        "description" : "Silver category"
      }   
... 

Setting the rate plan as public or private using the API

When creating a rate plan, you can specify whether it is public or private using the isPrivate attribute in the request body. If set to true, the rate plan will be private. For more information, see Public versus private rate plans.

For example, the following creates a private rate plan:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Simple rate plan",
     "currency": {
      "id" : "usd"
     },
     "description": "Simple rate plan",
     "displayName" : "Simple rate plan",     
     "monetizationPackage": {
      "id": "location"
     },
     "organization": {
      "id": "{org_name}"
     },     
     "published": true,
     "isPrivate" : true,
     "ratePlanDetails": [
     {
      …            
     }
     ],
     "startDate": "2013-09-15",
     "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location_package/rate-plans" \
-u email:password

 

Creating a rate plan revision using the API

You can create a revision of an existing rate plan. A revision is a new plan — the original plan and the revision both exist as rate plans. After an existing rate plan is published, the only property you can change is its end date. However, you can create a new version of the plan that includes changed properties, such as changed rate plan rates. You can set up the revision to go into effect at a future date. The original rate plan ends when the revision goes into effect.

This is a way of setting up a future rate plan using the API. For example, suppose you created a rate plan that expires on December 31, 2013 and you want to replace it with another plan that goes into effect on January 1, 2014. To do that, you can create a revision of the original rate plan and set it up to go into effect on January 1, 2014. For more information about creating future rate plans, see Create future rate plans.

Developers are notified about the revision. Those developers who accept the original rate plan are automatically registered for the revision (but have the option of rejecting the revision).

To create a rate plan revision, issue a POST request to /organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{plan_Id}/revision, where {package_id} is the identification of the API package, and {plan_Id} is the identification of the rate plan. When you create the revision, you need to specify in the request body the properties for the rate plan and the ID of the original rate plan (referred to as the parent rate plan).

For example, the following request creates a rate plan revision:

$ curl -H "Content-Type:application/json" -X POST -d \
'{ 
     "parentRatePlan": {
       "id": "monetization_package_flat_rate_card_plan_1379513833409"
     },
     "name": "Flat rate card plan",
     "developer":null,
     "developerCategory":null,
     "advance": "false",
     "currency": {
      "id" : "usd"
     },     
     "description": "Flat rate card plan",
     "displayName" : "Flat rate card plan",
     "frequencyDuration": "30",
     "frequencyDurationType": "DAY",
     "earlyTerminationFee": "10",     
     "monetizationPackage": {
      "id": "location"
     },
     "organization": {
      "id": "{org_name}"
     },
     "paymentDueDays": "30",
     "prorate": "false",
     "published": "true",
     "ratePlanDetails": [
     {
      "currency": {
       "id" : "usd"
      },
      "paymentDueDays": "30",      
      "meteringType": "UNIT",
      "organization": {
       "id": "myorg"
      },
      "ratePlanRates": [
       {
        "type": "RATECARD",
        "rate": "0.05",
        "startUnit": "0"       
       }      
      ],     
     "ratingParameter": "VOLUME",
     "type": "RATECARD"
     }],
     "recurringStartUnit": 1,
     "recurringType": "CALENDAR",
     "recurringFee": "10",
     "setUpFee": "10",
     "startDate": "2014-01-01 00:00:00",
     "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans/monetization_package_flat_rate_card_plan_1379513833409/revision" \
-u email:password

Configuration settings for rate plans

When creating a rate plan using the API, you can specify the following configuration ettings.

Name Description Default Required?
advance

Flag that specifies whether or not the recurring fee is charged in advance. Valid values include:

  • true - Recurring fee is charged in advance. For example, if the period is 1 month, the recurring fee is charged on the invoice generated when the prior billing month ends.
  • false - Recurring fee is charged at the end of the period. For example, if the period is 1 month, the recurring fee is charged on the invoice when the current billing month ends. This is the default.

 

false No
contractDuration

Length of the contract for the plan together with contractDurationType. For example, to specify a contract duration of 6 months, set contractDuration to 6 and contractDurationType to MONTH.

N/A No
contractDurationType

Length of the contract for the plan together with contractDuration. Valid values include:

  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR
N/A No
currency

Currency used for the rate plan. Specify the ISO 4217 code for the currency, such as usd for United States dollar or chf for Swiss franc.

N/A Yes
description

Description of the rate plan.

N/A Yes
developer

Developer ID. Specify for developer rate plans only.

N/A No
developerCategory

Developer category ID. Specify for developer category rate plans only.

N/A No
displayName

User-friendly display name for the rate plan.

N/A Yes
earlyTerminationFee

One-time fee that is charged if the developer ends the plan before the renewal term.

N/A No
endDate

Date that the plan ends. Developers are not able to view the rate plan after this date. If you don’t want the rate plan to end on a specific date, specify a null value for endDate.

N/A No
freemiumDuration

Period of time for the freemium period together with freemiumDurationType. For example, to specify that the freemium period is 30 days, set freemiumDuration to 30 and freemiumDurationType to DAY.

N/A No
freemiumDurationType

Period of time for the freemium period together with freemiumDuration. Valid values include:

  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR
N/A No
freemiumUnit

Freemium quantity. The value can be the number of transactions or the number of units pertaining to a custom attribute recorded in the transaction recording policy.

N/A No
frequencyDuration

Period of time between recurring fee charges together with frequencyDurationType. For example, to specify that the period of time between fee charges is 30 days, set frequencyDuration to 30 and frequencyDurationType to DAY.

N/A No
frequencyDurationType Period of time between recurring fee charges together with frequencyDuration. Valid values include:
  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR
N/A No
isPrivate Flag that specifies whether the rate plan is public or private. Defaults to false (public). For more information, see Public versus private rate plans. N/A No
monetizationPackage

API package ID for the rate plan.

N/A No
name

Name of the rate plan.

N/A Yes
organization

Organization ID for the rate plan.

N/A No
paymentDueDays

Number of days that fees are due. For example, set the value to 30 to indicate that fees are due in 30 days.

N/A No
proRate

Flag that specifies whether or not the recurring fee is prorated when a developer starts or ends a plan part of the way through a month. Valid values include:

  • true - Initial fee is prorated based on the number of days until the end of the period (or the number of days used in the period).
  • false - Developer is charged the full initial fee irrespective of when the developer starts (or ends) the plan. This is the default.

 

false No
published

Flag that specifies whether or not the rate plan should be published for viewing by developers. Valid values include:

  • true - Publish the rate plan.
  • false - Do not publish the rate plan.
N/A Yes
ratePlanDetails

Details for the rate plan (see Configuration settings for rate plan details).

N/A Yes
recurringFee

Fee that is charged to the developer on an ongoing basis until the developer ends the plan.

N/A No
recurringStartUnit

Valid only if recurringType is set to CALENDAR. Day of the month to charge the recurring fee. For example, if the recurring fee is charged monthly and recurringStartUnit is set to 1, the recurring fee is charged on the first day of each month.

N/A No
recurringType

Schedule for the recurring fee. Valid values include:

  • CALENDAR - Scheduled based on a calendar.
  • CUSTOM - Scheduled based on a custom date setting.

 

N/A No
setUpFee

One-time fee that is charged to each developer on the start date of the plan (that is, the date the developer purchases the plan).

N/A No
startDate

Date that the plan starts. Developers are able to view the rate plan starting on this date.

N/A Yes
type

Type of rate plan. Specify one of the following:

  • STANDARD. Applies to all developers.
  • DEVELOPER_CATEGORY. Applies to all developers in a selected category.
  • DEVELOPER. Applies to a specific developer.

 

N/A Yes

Configuration settings for rate plan details

You can specify any of the following configuration settings as part of the ratePlanDetails array when creating the rate plan.

Name Description Default Required?
aggregateFreemiumCounters

Flag that specifies whether or not aggregate counters are enabled to determine if usage of an API product is in the free range. Aggregate counters must be enabled to set up a freemium plan for a product. Valid values include:

  • true - Enable aggregate counters.
  • false - Do not enable aggregate counters.

 

N/A No
aggregateStandardCounters

Flag that specifies whether or not aggregate counters are used to determine the band of usage (such as a volume band for a rate card plan. The value can be one of the following:

  • true - Use aggregate counters.
  • false - Do not use aggregate counters.

 

N/A No
duration

Period of time for the aggregation basis, together with durationType. For example, set duration to 30 and durationType to DAY to specify an aggregation basis of 30 days.

N/A No
durationType

Period of time for the aggregation basis, together with durationType. Valid values include:

  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

For example, to specify an aggregation basis 30 days, set duration to 30 and durationType to DAY.

N/A No
freemiumDuration

Period of time for the freemium period for an individual API product together with freemiumDurationType. For example, to specify that the freemium period for an API product is 30 days, set freemiumDuration to 30 and freemiumDurationType to DAY.

N/A No
freemiumDurationType

Period of time for the freemium period for an individual API product together with freemiumDuration. Valid values include:

  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

For example, to specify that the freemium period for an API product is 30 days, set freemiumDuration to 30 and freemiumDurationType to DAY.

N/A No
freemiumUnit

Freemium quantity for an API product. The value can be the number of transactions or the number of units pertaining to a custom attribute recorded in the transaction recording policy.

N/A No
meteringType

Charging model for a rate card plan. Valid values include:

  • UNIT - Flat rate charging model.
  • VOLUME - Volume banded charging model.
  • STAIR_STEP - Bundled charging model.
  • DEV_SPECIFIC - Adjustable notification charging model. Not valid for any other revenue model.

 

N/A yes
paymentDueDays

Payment due date for a postpaid developer. For example, set the value to 30 to indicate that payment is due in 30 days.

N/A No
ratePlanRates

Rate plan rate details, such as the type of rate plan (REVSHARE or RATECARD), the rate for a rate card plan, the revenue share for a revenue share plan, and the range (starting unit and ending unit for which the rate plan rate applies).

N/A Yes
ratingParameter

Basis for the rate plan. The rate plan is based on transactions or on a custom attribute. Valid values include:

  • VOLUME - Rate plan is based on the volume of transactions.
  • MINT_CUSTOM_ATTRIBUTE_{num} - Rate plan is based on a custom attribute, whose name is of the form MINT_CUSTOM_ATTRIBUTE_{num}, where {num} is an integer for example, MINT_CUSTOM_ATTRIBUTE_1. This value is defined in the transaction recording policy for the API product and is valid for rate card plans only. The custom attribute name cannot be defined as VOLUME.

 

VOLUME Yes
ratingParameterUnit

Unit that applies to the ratingParameter

N/A Yes
revenueType

Basis of the revenue share in a revenue share plan. Valid values include:

  • GROSS - Revenue share is based on a percentage of the gross price of a transaction.
  • NET - Revenue share is based on a percentage of the net price of a transaction.

 

N/A No
type

Revenue model for the plan. Valid values include:

  • REVSHARE - Revenue share model.
  • RATECARD - Rate card model. 
  • REVSHARE_RATECARD - Revenue share and rate card model.
  • USAGE_TARGET - Adjustable notification model.

For more information about the revenue models, see Understanding the revenue models.

N/A Yes

Next steps

Help or comments?