Managing rate plans

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

Manage rate plans using the UI and API, as described in the following sections.

Exploring the rate plans page

Access the rate plans page, as described below.

Edge

To view rate plans in the Edge UI, access the Rate Plans page:

Sign in to apigee.com/edge.
Select Publish > Monetization > Rate Plans in the left navigation bar.

The Rate Plans page is displayed.

As highlighted in the figure, the Rate Plans page enables you to:

View summary information for all rate plans including plan name, API product bundle, status (published or draft), plan cost, and start and end dates.
NOTE: Expired rate plans are not displayed in the UI. To view expired rate plans, use the API. See Viewing rate plans using the API.
Create a rate plan
Edit a rate plan
Publish a rate plan
Delete a draft rate plan
Add a future rate plan, as described in Managing future rate plans
Search the list of rate plans on any visible field, or the developer name or category (if applicable)

Classic Edge (Private Cloud)

To view rate plans using the Classic Edge UI, access the API Packages page:

Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
Select Publish > Packages in the top navigation bar.

The API Packages page displays the rate plans defined for each package.

The Rate Plans page enables you to:

Create a rate plan
Edit a rate plan
Publish a rate plan
Delete a draft rate plan
Add a future rate plan, as described in Managing future rate plans
Search the list of rate plans on any visible field, or the developer name or category (if applicable)

Creating a rate plan

To create a rate plan:

Access the Rate Plans page.
Click +Rate Plan.

Configure the following fields in the top panel:

Field	Description	Default	Required
Rate plan name	Name of your rate plan. NOTE: The name must be unique within an API product bundle. Two plans in the same product bundle cannot have the same name.	N/A	Yes
Rate plan type	Rate plan type. Select a value from the drop-down list. For a list of valid rate plan types, see Supported rate plan types.	N/A	Yes
Product bundle	API product bundle. Select a value from the drop-down list. For more information about API product bundles, see Managing API product bundles. If you select a product bundle that contains more than one API product, you need to select whether to configure individual rate plans for each API product or a generic rate plan that will apply to all API products.	N/A	Yes
Audience	Audience that can access the rate plan. Select one of the following values from the drop-down list: Everyone - All developers. Developer - Developer or company. Enter the developer name or company. As you type, a list of the developers/companies that contain the string displays in a drop-down. Click the name of the developer or company from drop-down list. Developer category - Developer category. Select developer category from drop-down list. Configure developer categories as required, as described in Manage developer categories.	Everyone	No
Start date	Date the rate plan goes into effect. Enter a start date or select a date using the calendar.	Today	No
End date	Date the rate plan ends. To specify an end date, enable the Has End Date, toggle switch and enter an end date or select a date using the calendar. NOTE: 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, 2018, for example, you should set the endDate value to 2018-11-30. In this case, the rate plan will expire at the end of the day on November 30, 2018; all requests on December 1, 2018 will be blocked.	None	No
Visible to portals	Set whether the rate plan is Public or Private. See Public versus private rate plans.	Enabled	No

Configure fees for the rate plan. See Configuring fees for a rate plan.
NOTE: Not applicable to adjustable notification plans.

If you select a product bundle that contains more than one API product, set the following preferences in the Specific or generic rate plan section:
NOTE: This step is not applicable to adjustable notification plans.

Field	Description	Default
Configure each product individually	Flag that specifies whether to configure an individual rate plan for each API product.	Disabled
Configure each product's freemium offer individually	Flag that specifies whether to configure a freemium plan for each API product.	Disabled
Select a product	If you enable one or both of the flags, you must select each product individually from the drop-down list and configure its rate plan details. NOTE: Make sure that you configure all products in the product bundle.	N/A

Configure the rate plan details, based on the rate plan type selected:

Click one of the following:

Button	Description
Save as Draft	Save the rate plan as draft. The rate plan will not be visible to app developers until you publish it. You can edit any field in a draft rate plan.
Publish New Plan	Publish the plan. NOTE: After you publish a rate plan, you can only modify the end date if it is not already set. 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.

Attach the Monetization Limits Check policy to the API proxies associated with the API products included in the rate plan. The Monetization Limits Check policy enforces monetization limits on the API proxies and ensures that any faults are captured accurately in the analytics and monetization reports. For more information, see Enforce monetization limits on API proxies.

Editing a rate plan

You can edit all fields in a draft rate plan except for the Product Bundle, type, and audience. After you publish a rate plan, you can edit the end date only and only if no end date has been specified.

To edit a rate plan:

Access the Rate Plans page.
Click within the row of the rate plan that you want to edit.
The rate plan panel is displayed.
Edit the rate plan fields, as required.
NOTE: After you publish a rate plan, you can only modify the end date if it is not already set.

Click one of the following:

Button	Description
Update Draft (draft rate plans)	Save the rate plan as draft. The rate plan will not be visible to app developers until you publish it. You can edit any field in a draft rate plan.
Publish Draft (draft rate plans)	Publish the rate plan. NOTE: After you publish a rate plan, you can only modify the end date if it is not already set. 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.
Updated End Date (published rate plans)	Set the end date for a published plan. NOTE: After the end date is set for a published rate plan, it can no longer be modified.

Deleting a draft rate plan

Delete a draft rate plan if it is no longer needed.

NOTE: You cannot delete a published rate plan.

To delete a draft rate plan:

Access the Rate Plans page.
Position your cursor over the rate plan that you want to delete to display the actions menu.
Click .
Click Delete to confirm the action.

Managing rate plans using the API

The following sections describe how to manage rate plans using the API.

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 product bundle for which you create the rate plan (the ID is returned in the response when you create the API product bundle).

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

Organization ID
API product bundle 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, company, or developer 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 properties for rate plans.

If you create a rate plan (other than a fees only plan) for an API product bundle that has more than one product, you can apply the plan to a specific product in the product bundle. 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 product bundle.

The following sections describe how to create rate plans:

Creating a standard rate plan using the API
Creating a developer or company rate plan using the API
Creating a developer category rate plan using the API
Creating an API product-specific rate plan using the API
Setting the rate plan as public or private using the API

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 or company rate plan using the API

To apply the rate plan to a specific developer or company, set the type value to Developer. You also need to identify the developer or company in the request, identifying the ID, legal name, and name of the developer of company.

For example, the following excerpt creates a rate plan for the Dev Five developer:

...
     "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"
      }
...

Creating an API product-specific rate plan using the API

When creating a rate plan for API product bundles that include multiple API products, you can specify rate plan details for API products individually.

For example, the following creates a revenue share plan with two API products:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Multi-product rate plan",
     "currency": {
      "id" : "usd"
     },
     "description": "Multi-product rate plan",
     "displayName" : "Multi-product rate plan",
     "monetizationPackage": {
      "id": "mypackage",
      ...
     },
     "organization": {
      "id": "{org_name}",
      ...
     },
     "published": true,
     "isPrivate" : false,
     "ratePlanDetails": [
     {
        "ratePlanRates":[{
            "revshare":0,
            "startUnit":0,
            "type":"REVSHARE",
            "endUnit":null
        }],
       "revenueType":"NET",
       "type":"REVSHARE"
       "currency":{...},
       "product":{"id":"product1","displayName":"Product1"},
       "customPaymentTerm":false
     },
     {
        "ratePlanRates":[{
            "revshare":10,
            "startUnit":0,
            "type":"REVSHARE",
            "endUnit":null
        }],
       "revenueType":"NET",
       "type":"REVSHARE"
       "currency":{...},
       "product":{"id":"product2","displayName":"Product2"},
       "customPaymentTerm":false
     }
     ],
     "startDate": "2019-09-15",
     "type": "STANDARD"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/my-package/rate-plans" \
-u email:password

To add an API product to the my-package API product bundle, you'll need to add the rate plan details for the API product in the request body, as described in Adding an API product to an API product bundle with API product-specific rate plans.

Except for the ratePlanRates array, the values must match those specified for all other API products in the rate plan.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "ratePlan": [
    {
        "id": "my-package_multi-product-rate-plan",
        "ratePlanDetails": [
        {
            "ratePlanRates":[{
                "revshare":20,
                "startUnit":0,
                "type":"REVSHARE",
                "endUnit":null
             }],
             "revenueType":"NET",
             "type":"REVSHARE"
             "currency":{...},
             "customPaymentTerm":false
         }]
    }]
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/my-package/products/product3" \
-u email:password

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

Publishing a rate plan using the API

To publish a rate plan, set the published property value to true when you create the rate plan. Developers will be able to view the rate plan starting on the date specified in the startDate property for the plan.

For example, the following creates a rate card plan and publishes it (only part of the request is shown):

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Flat rate card plan",
     "developer":null,
     "developerCategory":null,
     "advance": "false",
     …
     "published": "true",
     "ratePlanDetails": [
     …
      ],
     …
     "type": "RATECARD"
     }],
     …
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

Saving a rate plan draft using the API

To save a rate plan without publishing it, set the published property value to false when you create the rate plan.

For example, the following creates a rate card plan and saves it as draft (only part of the request is shown):

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Flat rate card plan",
     "developer":null,
     "developerCategory":null,
     "advance": "false",
     …
     "published": "false",
     "ratePlanDetails": [
     …
      ],
     …
     "type": "RATECARD"
     }],
     …
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans" \
-u email:password

Editing a rate plan draft using the API

NOTE: If no end date is specified for a published rate plan, you can edit the endDate (only) if you wish to set an expiration date using this procedure. For more information, see Expire a published rate plan.

To update a rate plan draft, issue a PUT 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. When you make the update, you need to specify in the request body the updated settings and the ID of the rate plan. If you update a rate plan rate, you also need to specify the ID of the rate plan rate. For example, the following request updates the rate plan rate in a rate plan whose ID is location_flat_rate_card_plan (the update is highlighted):

$ curl -H "Content-Type: application/json" -X PUT -d \
 '{
      "id" : "location_flat_rate_card_plan",
      "name": "Flat rate card plan",
      "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": "false",
      "ratePlanDetails": [
      {
       "currency": {
        "id" : "usd"
       },
       "paymentDueDays": "30",
       "meteringType": "UNIT",
       "organization": {
        "id": "{org_name}"
       },
       "ratePlanRates": [
        {
         "id" : "26b69b0b-9863-48c9-ba73-74a5b918fcec",
         "type": "RATECARD",
         "rate": "0.15",
         "startUnit": "0"
        }
       ],
      "ratingParameter": "VOLUME",
      "type": "RATECARD"
      }],
      "recurringStartUnit": 1,
      "recurringType": "CALENDAR",
      "recurringFee": "10",
      "setUpFee": "10",
      "startDate": "2013-09-15 00:00:00",
      "type": "STANDARD"
 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans/location_flat_rate_card_plan" \
-u email:password

The response includes the updated rate plan rate (only part of the response is shown):

…
"ratePlanRates" : [ {
  "id" : "26b69b0b-9863-48c9-ba73-74a5b918fcec",
  "rate" : 0.15,
  "startUnit" : 0,
  "type" : "RATECARD"
} ],
…

Viewing rate plans using the API

You can view rate plans using the monetization API as described in the following sections.

Viewing all rate plans for an organization using the API
Viewing all rate plans for an API product bundle using the API
Viewing a rate plan for an API product bundle using the API
Viewing all active rate plans for a developer using the API
Viewing an accepted rate plan for a developer using the API
Viewing an accepted rate plan for a developer that contains an API product using the API
Viewing all rate plans accepted by a developer using the API

Viewing all rate plans for an organization using the API

To view all rate plans for an organization, issue a GET request to /mint/organizations/{org_name}/rate-plans, where {org_name} is the name of your organization.

You can pass the following query parameters to filter the results:

Query Parameter	Description
`all`	Flag that specifies whether to return all rate plans. If set to `false`, the number of rate plans returned per page is defined by the `size` query parameter. Defaults to `true`.
`size`	Number of API packages returned per page. If the `all` query parameter is set to `true`, this parameter is ignored.
`page`	Number of the page that you want to return (if content is paginated). If the `all` query parameter is set to `true`, this parameter is ignored.

For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/rate-plans" \
  -u email:password

Viewing all rate plans for an API product bundle using the API

To view all rate plans for an API package, issue a GET request to /mint/organizations/{org_name}/monetization-packages/{package_id}/rate-plans, where {package_id} is the ID of the API package (the package ID is returned when you create the monetization package).

By default, only active, public, and standard rate plans are returned in the results. To include:

Draft or expired rate plans, set the current query parameter to false (for example, ?current=false).
Private rate plans, set the showPrivate query parameter to true (for example, ?showPrivate=true).
All standard rate plans, set the standard query parameter to true (for example, ?standard=true).

For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/communications/rate-plans" \
  -u email:password

Viewing a rate plan for an API package using the API

To view a rate plan for an API package, issue a GET request to /mint/organizations/{org_name}/monetization-packages/{package_id}/rate-plans/{plan_id}, where {package_id} is the ID of the API package, and {plan_id} is the ID 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/myorg/monetization-packages/communications/rate-plans/communications_standard_fixed_plan" \
  -u email:password

The following provides an example of the response:

{
   "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",
   "isPrivate" : false,
   "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"
 }

Viewing all active rate plans for a developer using the API

To view all active rate plans for a developer, issue a GET request to /mint/organizations/{org_name}/developers/{developer_id}/developer-rateplans, where {developer_id} is the email address of the developer.

You can pass the following query parameters to filter the results:

Query Parameter	Description
`all`	Flag that specifies whether to return all API packages. If set to `false`, the number of API packages returned per page is defined by the `size` query parameter. Defaults to `false`.
`size`	Number of API packages returned per page. Defaults to 20. If the `all` query parameter is set to `true`, this parameter is ignored.
`page`	Number of the page that you want to return (if content is paginated). If the `all` query parameter is set to `true`, this parameter is ignored.

For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/developer-rateplans" \
  -u email:password

The following provides an example of the response:

{
  "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",
    "isPrivate" : false,
    "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
}

Viewing an accepted rate plan for a developer using the API

To view an active rate plan for a developer, issue a GET request to /mint/organizations/{org_name}/developers/{developer_id}/developer-rateplans/{developer_rateplan_id}, where {developer_id} is the email address of the developer, and {developer_rateplan_id} is the ID of the accepted rate plan that is returned in the response when you accept the published rate plan.

For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/developer-rateplans/messaging_package_fee_only_rateplan" \
  -u email:password

The following provides an example of the response:

{
    "created" : "2018-01-25 20:01:54",
    "developer" : {
    },
    "id" : "a73s104-276f-45b3-8075-83d1046ea550",
    "nextCycleStartDate" : "2018-02-19 00:00:00",
    "nextRecurringFeeDate" : "2018-02-19 00:00:00",
    "prevRecurringFeeDate" : "2018-01-25 00:00:00",
    "ratePlan" : {
      "frequencyDuration" : 1,
      "frequencyDurationType" : "MONTH",
      "recurringFee" : 0.0000,
      "recurringStartUnit" : 19,
      "recurringType" : "CALENDAR",
      "setUpFee" : 0.0000,
      "type" : "STANDARD"
    },
    "startDate" : "2018-01-25 20:01:54",
    "updated" : "2018-01-25 20:01:54"
  }

Viewing an accepted rate plan for a developer that contains an API product using the API

To view an accepted rate plan for a developer that contains an API product, issue a GET request to /mint/organizations/{org_id}/developers/{developer_id}/products/{product_id}/rate-plan-by-developer-product, where {developer_id} is the ID of the developer and /{product_id} is the ID of the product.

By default, only a public rate plan is returned in the results. To display a private rate plan, set the showPrivate query parameter to true (for example, ?showPrivate=true).

For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/products/location/rate-plan-by-developer-product" \
  -u email:password

Viewing all rate plans accepted by a developer using the API

To view rate plans that have been accepted by a developer, issue a GET request to /mint/organizations/{org_name}/developers/{developer_id}/developer-accepted-rateplans, where {developer_id} is the ID of the developer.

You can pass the following query parameters to filter the results:

Query Parameter	Description
`all`	Flag that specifies whether to return all API packages. If set to `false`, the number of API packages returned per page is defined by the `size` query parameter. Defaults to `false`.
`size`	Number of API packages returned per page. Defaults to 20. If the `all` query parameter is set to `true`, this parameter is ignored.
`page`	Number of the page that you want to return (if content is paginated). If the `all` query parameter is set to `true`, this parameter is ignored.

For example:

curl -H "Accept:application/json" -X GET \
  "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/developers/dev@mycompany.com/developer-accepted-rateplans" \
  -u email:password

The following provides an example of the response:

{
  "developerRatePlan" : [ {
     "created" : "2018-01-25 20:01:54",
     "developer" : { ...
     },
     "id" : "a73s104-276f-45b3-8075-83d1046ea550",
     "nextCycleStartDate" : "2018-02-19 00:00:00",
     "nextRecurringFeeDate" : "2018-02-19 00:00:00",
     "prevRecurringFeeDate" : "2018-01-25 00:00:00",
     "ratePlan" : {
       "frequencyDuration" : 1,
       "frequencyDurationType" : "MONTH",
       "recurringFee" : 0.0000,
       "recurringStartUnit" : 19,
       "recurringType" : "CALENDAR",
       "setUpFee" : 0.0000,
       "type" : "STANDARD"
     },
     "startDate" : "2018-01-25 20:01:54",
     "updated" : "2018-01-25 20:01:54"
   }],
   "totalRecords" : 1
}

Deleting a rate plan draft using the API

To delete a rate plan draft, issue a DELETE request to /organizations/{org_name}/monetization-packages/package_id}/rate-plans/{plan_Id}, where {plan_Id} is the identification of the rate plan to be deleted, and {package_id} is the identification of the API package for the rate plan. For example:

$ curl -H "Accept:application/json" -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/location/rate-plans/location_flat_rate_card_plan" \
-u email:password

Configuration properties for rate plans

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

Name	Description	Default	Required?
`advance`	Valid for recurring fees only. 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 (email address). 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`. 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, 2016, for example, you should set the endDate value to 2016-11-30. In this case, the rate plan will expire at the end of the day on November 30, 2016; all requests on December 1, 2016 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
`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`	Valid for recurring fees only. 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`	Valid for recurring fees only. 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 product bundle 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	Yes
`paymentDueDays`	Valid for recurring fees only. 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`	Valid for recurring fees only. 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 properties 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 or company.	N/A	Yes

Configuration properties for rate plan details

You can specify any of the following configuration proerties 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
`aggregateTransactions`	NOTE: This property is not currently used by monetization and can be ignored.	true	No
`currency`	Currency.	N/A	No
`duration`	Period of time for the calculation frequency, together with `durationType`, where the allowed `duration` values are 1-24. For example, set `duration` to `2` and `durationType` to `MONTH` to specify a calculation frequency of 2 months. "Calculation frequency" was previously referred to as "aggregation basis". The term "aggregation basis" is deprecated.	N/A	No
`durationType`	Period of time for the calculation frequency, together with `duration`. The only valid value is `MONTH`. See `duration` for a usage example.	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
`organization`	Organization ID.	N/A	No
`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
`product`	API product information, such as ID.	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. custom_attribute - Name of a custom attribute that 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. Only required if`ratingParameter is set to a custom attribute (that is, not set to VOLUME).	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`	Rate plan type. 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 rate plan types, see Supported rate plan types.	N/A	Yes