Managing rate plans

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:

  1. Sign in to apigee.com/edge.
  2. 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:

Classic Edge (Private Cloud)

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

  1. Sign in to http://ms-ip:9000, where ms-ip is the IP address or DNS name of the Management Server node.
  2. 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:

Creating a rate plan

To create a rate plan:

  1. Access the Rate Plans page.
  2. Click +Rate Plan.
  3. 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
  4. Configure fees for the rate plan. See Configuring fees for a rate plan.
    Note: Not applicable to adjustable notification plans.
  5. 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
  6. Configure the rate plan details, based on the rate plan type selected:
  7. 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.

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:

  1. Access the Rate Plans page.
  2. Click within the row of the rate plan that you want to edit.
    The rate plan panel is displayed.
  3. 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.
  4. 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:

  1. Access the Rate Plans page.
  2. Position your cursor over the rate plan that you want to delete to display the actions menu.
  3. Click .
  4. 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

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.

$ 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

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

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 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-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 ID 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. 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 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
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