Was this helpful?

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.

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

You have a lot of flexibility in creating rate plans. To start, you create either a standard rate plan that applies to all developers, a developer category rate plan that applies to all developers in a particular developer category, or a developer rate plan that applies to a specific developer. In each case, you have many additional options.

For example, you can:

  • Set a one-time or recurring fee for the 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.
  • Configure a rate plan type. You have various choices such as a revenue share plan, where you 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.
  • 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.

Toolbox

You can create rate plans using the management UI or monetization API. If you use the UI, you create a rate plan by selecting a package in the package catalog and then clicking + Add Rate Plan.

If you 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 initially create rate plans, you can perform management operations on them such as update or delete. Management operations on a rate plan are performed by issuing calls to the /organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{plan_id} resource.

Creating a rate plan in the UI

You create either a standard rate plan, a developer rate plan, or a developer category rate plan.

Creating a standard rate plan using the UI

A standard rate plan applies to 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.

To create a standard rate plan:

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

    This opens the Rate Plan window.

  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. Add fees to a rate plan (optional).
  5. Add a freemium plan (optional).
  6. Specify plan details (optional).
  7. Publish the plan or save it as a draft (see Publish rate plans).

Creating a developer rate plan using the UI

A developer rate plan applies to a 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.

To create a developer rate plan:

  1. Click + Add Rate Plan next to the pertinent 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 Give developers access to your API.

  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. Add fees to a rate plan (optional).
  6. Add a freemium plan (optional).
  7. Specify plan details (optional).
  8. Publish the plan or save it as a draft (see Publish rate plans).

Creating a developer category rate plan using the UI

A developer category rate plan applies to all developers in a selected category. (See Create developer categories for instructions on how to create developer categories.) You can create a developer category rate plan only if developer categories have been previously created.

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 Developers for further details.

To create a developer category rate plan:

  1. Click + Add Rate Plan next to the pertinent 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. 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. Add fees to a rate plan (optional).
  5. Add a freemium plan (optional).
  6. Specify plan details (optional).
  7. Publish the plan or save it as a draft (see Publish rate plans).

Creating a rate plan 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 identification 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:

  • The organization ID
  • The API package ID
  • The name of the rate plan
  • A description of the rate plan
  • The date when the rate plan goes into effect
  • The currency for the rate plan
  • Whether you want the rate plan to be published

In addition, you need to specify the type of rate plan you want. The choices are:

  • STANDARD. A rate plan that applies to 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 developer portal, starting on the effective date of the plan.
  • DEVELOPER. A rate plan that applies to a specific developer. After you create and publish the rate plan, the developer will be able to see it (and the API package) listed in the catalog in the developer portal, starting on the effective date of the plan.
  • DEVELOPER_CATEGORY. A rate plan that applies to all developers in a selected category. (See Manage developers for instructions on how to create developer categories.) You can create a developer category rate plan only if developer categories have been previously created. 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 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 the section "Adding a developer to a developer category" in Manage developers for further details.

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

You also need to specify details about the rate plan, such as the applicable revenue model and whether the plan applies to all the products in the API package or to a specific product in the package. See Specify plan details for further information.

Optionally, you can:

After you create a rate plan, you can publish the plan or save it as a draft (see Publish rate plans).

Creating a standard rate plan using the API

The following example shows basic information that you need to specify to create a standard rate plan. (The rate plan details are not shown. To learn about adding rate plan details, see Specifying rate plan details.)

$ 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",
     "ratePlanDetails": [
     {
      …            
     }
     ],
     "startDate": "2013-09-15",
     "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location_package/rate-plans" \
-u myname:mypass

Creating a developer rate plan using the API

To apply the rate plan to a specific developer, replace the type value with 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, replace the type value with 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"
       {   
... 

Retrieving rate plans using the API

You can retrieve a specific rate plan or all rate plans in an organization. You can also retrieve all rate plans or a specific rate plan available to an individual developer. When you retrieve rate plans available to a developer the response includes rate plans that have been "accepted" (that is, purchased) by the developer and those that are not yet accepted. You can limit the retrieval of these rate plans to only those that have been accepted.

Retrieving a specific rate plan in an organization: To retrieve a specific rate plan, issue a GET request to /organizations/{org_name}/monetization-packages/package_id/rate-plans/{plan_id}, where {package_id} is the identification of the API package, and {plan_id} is the identification of the rate plan (the package ID is returned when you create the monetization package, and the rate plan ID is returned when you create the rate plan). For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/communications/rate-plans/communications_standard_fixed_plan" \
-u myname:mypass

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

{
   "advance" : true,
   "contractDuration" : 1,
   "contractDurationType" : "YEAR",
   "currency" : {
     "id" : "usd",
     ...
     "organization" : {
       ...
     },
     ...
   },
   "description" : "Standard Fixed Plan",
   "displayName" : "Standard Fixed Plan",
   "earlyTerminationFee" : 0.0000,
   "frequencyDuration" : 1,
   "frequencyDurationType" : "MONTH",
   "id" : "communications_standard_fixed_plan",
   "monetizationPackage" : {
     "description" : "Communications",
     "displayName" : "Communications",
     "id" : "communications",
     "name" : "Communications",
     "organization" : {
      ...
     },
     "product" : [ {
       "customAtt1Name" : "user",
       "description" : "Location",
       "displayName" : "Location",
       "id" : "location",
       "name" : "location",
       "organization" : {
       ...
       },
       "status" : "CREATED"
     }, {
       "customAtt1Name" : "user",
       "description" : "Messaging",
       "displayName" : "Messaging",
       "id" : "messaging",
       "name" : "messaging",
       "organization" : {
         ...
       },
       "status" : "CREATED"
     } ],
     "status" : "CREATED"
   },
   "name" : "Standard Fixed Plan",
   "organization" : {
     ...
   },
   "paymentDueDays" : "30",
   "prorate" : true,
   "published" : true,
   "ratePlanDetails" : [ {
     "aggregateFreemiumCounters" : true,
     "aggregateStandardCounters" : true,
     "currency" : {
       "id" : "usd",
       "name" : "USD",
       "organization" : {
        ...
       },
       "status" : "ACTIVE",
       "virtualCurrency" : false
     },
     "id" : "cb92f7f3-7331-446f-ad63-3e176ad06a86",
     "meteringType" : "UNIT",
     "organization" : {
      ...
     },
     "paymentDueDays" : "30",
     "ratePlanRates" : [ {
       "id" : "07eefdfb-4db5-47f6-b182-5d606c6051c2",
       "rate" : 0.0500,
       "startUnit" : 0,
       "type" : "RATECARD"
     } ],
     "ratingParameter" : "VOLUME",
     "type" : "RATECARD"
   } ],
   "recurringFee" : 200.0000,
   "recurringStartUnit" : 1,
   "recurringType" : "CALENDAR",
   "setUpFee" : 100.0000,
   "startDate" : "2013-01-11 22:00:00",
   "type" : "STANDARD"
 }

Retrieving all rate plans in an organization: To retrieve all rate plans for an organization, issue a GET request to /organizations/{org_name}/monetization-packages/package_Id/rate-plans. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/communications/rate-plans" \
-u myname:mypass

Retrieving all rate plans available to a specific developer: To retrieve all rate plans available to a specific developer, issue a GET request to /organizations/{org_name}/developers/{developer_id}/developer-rateplans, where {developer_id} is the identification of the developer. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev7@myorg.com/developer-rateplans" \
-u myname:mypass

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

{
  "ratePlan" : [ {
    "advance" : true,
    "contractDuration" : 1,
    "contractDurationType" : "MONTH",
    "currency" : {
      "description" : "United States Dollar",
      "displayName" : "United States Dollar",
      "id" : "usd",
      "name" : "USD",
      "organization" : {
        ...
      },
      "status" : "ACTIVE",
      "virtualCurrency" : false
    },
    "description" : "Fee Only RatePlan",
    "displayName" : "Fee Only RatePlan",
    "earlyTerminationFee" : 10.0000,
    "freemiumDuration" : 0,
    "freemiumDurationType" : "MONTH",
    "freemiumUnit" : 0,
    "frequencyDuration" : 1,
    "frequencyDurationType" : "WEEK",
    "id" : "messaging_package_fee_only_rateplan",
    "monetizationPackage" : {
      "description" : "messaging package",
      "displayName" : "Messaging Package",
      "id" : "messaging_package",
      "name" : "Messaging Package",
      "organization" : {
        ...
      },
      "product" : [ {
        "customAtt1Name" : "user",
        "customAtt2Name" : "response size",
        "customAtt3Name" : "content-length",
        "description" : "messaging api product",
        "displayName" : "messaging",
        "id" : "messaging",
        "name" : "messaging",
        "organization" : {
         ...
        },
        "status" : "CREATED",
        "transactionSuccessCriteria" : "status == 'SUCCESS'"
      } ],
      "status" : "CREATED"
    },
    "name" : "Fee Only RatePlan",
    "organization" : {
     ...
    },
    "paymentDueDays" : "30",
    "prorate" : false,
    "published" : true,
    "ratePlanDetails" : [ ],
    "recurringFee" : 10.0000,
    "recurringStartUnit" : 1,
    "recurringType" : "CALENDAR",
    "setUpFee" : 20.0000,
    "startDate" : "2013-02-20 00:00:00",
    "type" : "STANDARD"
  } ],
  "totalRecords" : 1
}

Retrieving an individual rate plan available to a specific developer: To retrieve an individual rate plan that is available to a specific developer, issue a GET request to /organizations/{org_name}/developers/{developer_id}/developer-rateplans/{plan_id}, where {developer_id} is the identification of the developer, and {plan_id} is the identification of the rate plan. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev7@myorg.com/developer-rateplans/messaging_package_fee_only_rateplan/messaging_package_fee_only_rateplan" \
-u myname:mypass

Retrieving rate plans available to a specific developer that contain a specific product: You can retrieve rate plans that contain a specific API product and that are available to a specific developer. To do that, issue a GET request to /organizations/{org_id}/developers/{developer_id}//products/{product_id}/rate-plan-by-developer-product, where {developer_id} is the identification of the developer and /{product_id} is the identification of the product. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev7@myorg.com/products/location/rate-plan-by-developer-product" \
-u myname:mypass

Retrieving rate plans accepted by a developer: You can limit the retrieval of rate plans available to a developer to only those that have been accepted by the developer. To do that, issue a GET request to /organizations/{org_name}/developers/{developer_id}/developer-accepted-rateplans, where {developer_id} is the identification of the developer. For example:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/dev7@myorg.com/developer-accepted-rateplans" \
-u myname:mypass

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 myname:mypass

Rate plan configuration settings

The following rate plans configuration options are exposed to the API:

Name Description Default Required?
name

The name of the rate plan.

N/A Yes
displayName

The name displayed for the rate plan.

N/A Yes
description

A description of the rate plan.

N/A Yes
organization

The organization for the rate plan. Specify the ID of the organization.

N/A No
monetizationPackage

The API package for the rate plan. Specify the ID of the package.

N/A No
developer

The developer for a developer rate plan. Specify the ID of the developer.

N/A No
developerCategory

The developer category for a developer category rate plan. Specify the ID of the developer category.

N/A No
currency

The 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
type

The type of rate plan. Specify one of the following:

  • STANDARD. A rate plan that applies to all developers.
  • DEVELOPER_CATEGORY. A rate plan that applies to all developers in a selected category.
  • DEVELOPER. A rate plan that applies to a specific developer.

 

N/A Yes
setUpFee

A 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). Specify the amount to be charged.

N/A No
earlyTerminationFee

A one-time fee that is charged if the developer ends the plan before the renewal term. Specify the amount to be charged.

N/A No
recurringFee

A fee that is charged to the developer on an ongoing basis until the developer ends the plan. Specify the amount to be charged.

N/A No
recurringType

Indicates how the recurring fee is scheduled. Specify one of the following:

  • CALENDAR. The recurring fee is scheduled based on a calendar.
  • CUSTOM. The recurring fee is scheduled based on a custom date setting.

 

N/A No
recurringStartUnit

Used only if recurringType is set to CALENDAR. Indicates the 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
frequencyDuration

Together with frequencyType, indicates the period of time between recurring fee charges. 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 frequencyDuration, indicates the period of time between recurring fee charges. The frequencyDurationType value can be one of the following:
  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

 

N/A No
proRate

Indicates whether or not the recurring fee is prorated. This pertains to the developer starting or ending the plan part of the way through a month. The value can be one of the following:

  • true. The 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. The developer is charged the full initial fee irrespective of when the developer starts (or ends) the plan. This is the default.

 

false No
advance

Indicates whether or not the recurring fee is charged in advance. The value can be one of the following:

  • true. The 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. The 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
paymentDueDays

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

N/A No
freemiumDuration

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

N/A No
freemiumDurationType

Together with freemiumDuration, indicates the period of time for the freemium period. The freemiumDurationType value can be one of the following:

  • DAY
  • WEEK
  • MONTH
  • QUARTER
  • YEAR

 

N/A No
freemiumUnit

Specifies the 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
startDate

The date when the plan starts. Developers are able to view the rate plan starting on this date.

N/A Yes
endDate

The date when 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
published

Indicates whether or not the rate plan should be published for viewing by developers. The value can be one of the following:

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

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

N/A No
contractDurationType

Together with contractDuration, indicates the length of the contract for the plan. The contractDurationType value can be one of the following:

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

The details for the rate plan (see Rate plan details configuration settings).

N/A Yes

Get help

For help, see Apigee Customer Support.

Next steps

If you want to establish fees for your rate plan, see Add fees to a rate plan.

If you want to add a "freemium" part to the plan, see Add a freemium plan.

To further configure you rate plan, such as specifying the applicable revenue model, see Specify plan details.

When you're ready to publish your rate plan, see Publish rate plans.

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.