Send Docs Feedback

Accept published rate plans using the API

This section describes how to accept a published rate plan, and expire or cancel an accepted rate plan, if desired, using the API.

Accepting a published rate plan

After a rate plan is published, a developer or company can "accept" (or purchase) it by issuing a POST request to /organizations/{org_name}/developers/{developer_or_company_id}/developer-rateplans, where {org_name} is the name of the organization and {developer_or_company_id} is the ID of the developer or company.

If an individual developer is accepting the rate plan (that is, you specify a developer ID), then the following monetization attributes must be defined for the developer: MINT_DEVELOPER_ADDRESS and MINT_DEVELOPER_LEGAL_NAME. Otherwise, the following error message displays: Developer legal name not specified. For information about updating the developer attributes, see the following sections:

To waive setup fees when accepting a rate plan, set the waivefees query parameter to true. This flag is useful when you are migrating developers to monetization, as described in Migrating developers to monetization.

The following table summarizes the configuration properties that you can specify in the request body, their default values, and whether or not they are required.

Name Description Default Required?
startDate

Date when the rate plan starts. For example: 2017-03-24.

N/A Yes
endDate

Date when the rate plan ends. For example: 2017-09-24.

The rate plan will be in effect until the end of the day on the date specified. If you want to expire a rate plan on December 1, 2017, for example, you should set the endDate value to 2017-11-30. In this case, the rate plan will expire at the end of the day on November 30, 2017; all requests on December 1, 2017 will be blocked. 

Note: When viewing the rate plan using the API, the endDate time stamp is specified as YYYY-MM-DD 00:00:00, which may be misleading.

N/A No
developer

id property that defines the ID of the developer or company that is accepting the rate plan.

N/A Yes
quotaTarget

Note: This property is valid for adjustable notification rate plans only. See Specify adjustable notification plan details.

Target number of transactions allowed for the app developer. You can configure if and when notifications are sent based on what percentage of the target number has been reached, such as 90%, 100%, or 150%. Additional transactions are not blocked after the target number is reached.

Set this value to a positive integer value or 0 to disable notifications for an app developer.

0 No
ratePlan

id property that defines the ID of the rate plan. 

The rate plan ID is different from the display name. To view rate plan details including the ID, see View rate plans.

N/A Yes
suppressWarning

Flag that specifies whether to suppress the error if the developer attempts to accept a rate plan that overlaps another accepted rate plan. The value can be one of the following:

  • true - Monetization terminates all accepted rate plans that the developer has to API packages that contain the conflicting API products. It then accepts a new API package for the developer.
  • false - An error is thrown in the event that there is an overlapping rate plan.
N/A No
waveTerminationCharge

Flag that specifies whether termination fees are waved when an active rate plan is terminated as part of activating the new rate plan. The value can be one of the following:

  • true - Wave the termination fee when an active rate plan is terminated as part of activating the new rate plan.
  • false - Do not wave the termination fee when an active rate plan is terminated as part of activating new rate plan.
N/A No

For example, the following request accepts the location_&_messaging rate plan for the specified developer:

$ curl -H "Content-Type:application/json" -X POST -d \
'{ 
   "developer":{
     "id":"5cTWgdUvdr6JW3xU"
   },
   "startDate":"2017-08-30",
   "ratePlan":{
     "id":"location_&_messaging"
   },
   "suppressWarning":false
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/developer-rateplans" \
-u email:password

In this example, the suppressWarning property is set to false. In this case, an error will be thrown in the event of a conflict. For example, if the developer attempts to accept a rate plan that overlaps another accepted rate plan, an error is thrown. This enables an application that provides a user interface to monetization to intercept the error and display the conflicting products to the developer for confirmation (as appropriate). If suppressWarning is set to true, monetization terminates all accepted rate plans that the developer has to API packages that contain the conflicting products. It then accepts a new API package for the developer.

The following request accepts an adjustable notification rate plan and sets the target number of transactions to 4000.

$ curl -H "Content-Type:application/json" -X POST -d \
'{ 
   "developer":{
     "id":"5cTWgdUvdr6JW3xU"
   },
   "ratePlan":{
     "id":"adjustable-notification-plan"
   },
   "startDate": "2017-03-24",
   "quotaTarget": 4000,
   "suppressWarning":false
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/5cTWgdUvdr6JW3xU/developer-rateplans" \
-u email:password

In either of the examples above, if the following error message is returned:

Developer legal name not specified. 

Then you must set the monetization attributes MINT_DEVELOPER_ADDRESS and MINT_DEVELOPER_LEGAL_NAME, and then repeat the API call.

Expiring a rate plan accepted by a developer

To expire (or cancel) a rate plan that has been accepted by a developer, update the accepted rate plan details and specify the endDate property in the request body in a PUT request to the /organizations/{org_name}/developers/{developer_or_company_id}/developer-rateplans/{developer_rateplan_id} resource.

The rate plan will be in effect until the end of the day on the end date specified. If you want to expire a rate plan on December 1, 2017, for example, you should set the endDate value to 2017-11-30. In this case, the rate plan will expire at the end of the day on November 30, 2017; all requests on December 1, 2017 will be blocked.

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

For example:

{
  "created": "2017-03-31 18:59:54",
  "developer": {
    ...
  },
  "id": "b1c600b8-f871-496d-8173-12b9950d6ab1",
  "quotaTarget": 3000,
  "ratePlan": {
    ...
  },
  "startDate": "2017-03-31 00:00:00",
  "updated": "2017-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 identification of the developer. For more information, see Viewing all rate plans accepted by a developer.

The following request updates the end date to December 1, 2017. That is, the rate plan will expire at the end of the day on November 30, 2017; all requests on December 1, 2017 will be blocked.

$ 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": "2017-04-15 00:00:00",
   "endDate": "2017-11-30",
   "quotaTarget": 3000,
   "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

Get help

For help, see Apigee Customer Support.

Help or comments?