Purchase rate plans using the API

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

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

Purchasing a published rate plan using the API

After a rate plan is published, a developer or company can purchase (or "accept") it by issuing a POST request to /mint/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.

Note: If an individual developer is purchasing the rate plan (that is, you specify a developer ID (email address)), 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 purchasing 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 purchasing the rate plan.	N/A	Yes
`quotaTarget`	Note: This property is valid for adjustable notification rate plans only. See Configure adjustable notification plan. 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 Exploring the rate plans page.	N/A	Yes
`suppressWarning`	Flag that specifies whether to suppress the error if the developer attempts to purchase a rate plan that overlaps another purchased rate plan. The value can be one of the following: `true` - Monetization terminates all purchased rate plans that the developer has to API packages that contain the conflicting API products. It then purchases 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 waived when an active rate plan is terminated as part of activating the new rate plan. The value can be one of the following: `true` - Waive the termination fee when an active rate plan is terminated as part of activating the new rate plan. `false` - Do not waive 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 purchases the location_&_messaging rate plan for the specified developer:

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

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 purchase a rate plan that overlaps another purchased 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 purchased rate plans that the developer has to API packages that contain the conflicting products. It then purchases a new API package for the developer.

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

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

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 purchased by a developer using the API

To expire (or cancel) a rate plan that has been purchased by a developer, update the purchased 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 purchase 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 email address of the developer. For more information, see Viewing all rate plans purchased 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 "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/developer-rateplans/b1c600b8-f871-496d-8173-12b9950d6ab1"
  -X PUT \
  -H "Content-Type:application/json" \
  -u email:password \
  -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
  }'