Configure rate card plan

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

Introduction

In a rate card plan, the developer is charged for each transaction. For this type of plan, you need to provide additional details, such as the charging model and pricing for the charging model.

Optionally, you can specify a freemium plan for individual products (rather than for an API package) — you can do this only for a product-specific plan.

When are recurring fees charged and bundle plans reset?

Rate plans can include recurring fees as well as API bundles (Volume Banded and Bundle plans), both of which involve a specific times when fees are charged and bundle plans reset to zero. The following table describes when recurring fees are charged and bundle counts are reset. If developer apps are blocked from making further API calls because they're reached a certain transaction limit, these are the times when counts for API calls are reset to zero and the apps can begin making calls again.

If the plan has...	...this happens
A non-zero recurring fee set to Month A Volume Banded or Bundle plan	The recurring fee and bundle plan reset occur on the first of the month (default). For a monthly recurrence on a specific day, create a rate plan using the management API and indicate the day with a RecurringStartUnit property, as described in Creating rate plans using the API.
A non-zero recurring fee set to Week A Volume Banded or Bundle plan	The recurring fee and bundle plan reset occur every 7 days after the developer's rate plan start date.
A non-zero recurring fee set to Day A Volume Banded or Bundle plan	The recurring fee and bundle plan reset occur every X days after the developer's rate plan start date.
No (or a zero-dollar) recurring fee A Volume Banded or Bundle plan	Bundle plans are reset based on the Aggregation Basis defined on the rate card. For example, if a developer starts a rate plan on the 19th of the month, and the Aggregation Basis is every 1 month, then the bundle use is reset every month on the 19th. Note that the day of the month might not always be the same. For example, if a rate plan starts on the December 31, the reset date becomes the 28th in a non-leap-year February since there are only 28 days in February. The 28th then remains the reset day ever after.

Configuring rate card plans using the UI

Configure rate card plans, as described below.

Configuring the rate card plan using the API

Configure the rate card plan details using the API, as described in the following sections.

Specifying rate card plan details using the API

You specify rate card plan details when you create the rate plan. You specify the details in the ratePlanDetails property within the request body in a call to /organizations/{org_name}/monetization-packages/{package_id}/rate-plans. What you specify in the ratePlanDetails property, depends on the charging model you choose: flat rate, volume banded, or bundles.

Specifying a flat rate charging model

To implement the flat rate charging model, you specify the following in the rate plan details:

• A rating parameter that indicates that the rate plan is based on transactions (VOLUME) or based on a custom attribute (for example, MINT_CUSTOM_ATTRIBUTE_1). VOLUME is the default.
• A metering type (UNIT) that indicates that the rate is fixed per unit (that is, it’s not based on the volume of transactions, as is the case for the volume banded or bundles charging model).
• The payment due period (for example, 30 days).
• The ID of your organization.
• The "base" or accounting currency that your company uses.
• A rate plan rate that provides details about how the rate is calculated. Because the charging model is based on a fixed rate, you only specify one rate plan rate.

In the rate plan rate, you specify:

• The type of the rate plan rate (RATECARD).
• The rate for the plan. For example, if you specify 0.10, and the currency is U.S. dollars, the developer is charged $0.10 for each transaction (or if based on a custom attribute such as the number of bytes transmitted in a transaction, the developer is charged $0.10 for transmitting the specified number of bytes).
• The starting unit of the rate application (0). This means that the rate is applied to each transaction, starting with the first transaction.

See Rate plan details configuration settings for a complete list of rate plan detail options.

For example, the following creates a rate card plan with a fixed charging model. The rate is set at $0.10 for each transaction. Payment is due in 30 days. (The rate card-related details are highlighted.)

curl -H "Content-Type:application/json" -X POST -d \
'{ 
     "name": "Flat rate card plan",
     "developer":null,
     "developerCategory":null,
     "advance": "false",
     "currency": {
      "id" : "usd"
     },     
     "description": "Flat rate card plan",
     "displayName" : "Flat rate card plan",
     "frequencyDuration": "30",
     "frequencyDurationType": "DAY",
     "earlyTerminationFee": "10",     
     "monetizationPackage": {
      "id": "location"
     },
     "organization": {
      "id": "{org_name}"
     },
     "paymentDueDays": "30",
     "prorate": "false",
     "published": "true",
     "ratePlanDetails": [
     {
      "currency": {
       "id" : "usd"
      },
      "paymentDueDays": "30",      
      "meteringType": "UNIT",
      "organization": {
       "id": "{org_name}"
      },
      "ratePlanRates": [
       {
        "type": "RATECARD",
        "rate": "0.10",
        "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" \
-u email:password

Specifying a volume banded charging model

In a volume banded model, you specify rate plan details that include one or more rate plan rates, each rate applies to a "volume band", that is, a range of transaction volume (or a range based on a custom attribute such as the number of bytes transmitted). This type of plan is usually set up to encourage developers to generate higher volumes by offering discounted rates for higher volume bands.

In addition to the rate plan rates, you specify the following in the rate plan details:

• A rating parameter that indicates that the rate plan is based on transactions (VOLUME) or based on a custom attribute (for example, CUSTOM_ATTRIBUTE_1). VOLUME is the default.
• A metering type (VOLUME) that indicates that the rate is based on the volume of transactions (that is, it’s not a flat rate per transaction, as is the case for the flat rate charging model).
• The payment due period (for example, 30 days).
• The ID of your organization.
• The "base" or accounting currency that your company uses.
• A duration and duration type that together specify the period of time over which the volume of transactions (or custom attribute-related volume) is aggregated. This is also termed an "aggregation basis". The volume of transactions is aggregated over the aggregation basis (for example, 1 month) to determine the applicable volume band.
• Aggregation counters that are used to determine the applicable volume band.

For each rate plan rate, you specify:

• The type of the rate plan rate (RATECARD).
• The rate for the plan. For example, if you specify 0.10, and the currency is U.S. dollars, the developer is charged $0.15 for each transaction (or if based on a custom attribute such as the number of bytes transmitted in a transaction, the developer is charged $0.15 for transmitting the specified number of bytes).
• The starting and ending unit of the volume band. The starting unit specifies the lower limit of the volume band, and the ending unit specifies the upper limit of the volume band. For example, if you specify a starting unit of 0 and an ending unit of 1000, the volume band covers up to 1000 transactions in the aggregation period. If the currency is U.S. dollars the aggregation period is 1 month, and the rate for the first 1000 transactions is 0.15, the developer is charged $0.15 per transaction for up to 1000 transactions in the month.
  
  For details on when bundles are reset, see When are recurring fees charged and bundle plans reset?
  

  If you don’t specify an ending unit for final volume band, the rate for that band is applied to all transactions after the number of transactions has gone above the starting unit for that band. For example if the starting unit for the last band is 1000, and you do not specify an ending unit for that band, the rate for the band is applied to all transactions after 1000 transactions in the aggregation period.

See Rate plan details configuration settings for a complete list of rate plan detail options.

For example, the following creates a rate card plan with a volume banded charging model. The rate is set at $0.15 for the first 1000 transactions, and $0.10 for all transactions over 1000. The aggregation basis is 1 month. Payment is due in 30 days. (The rate card details are highlighted.)

curl -H "Content-Type:application/json" -X POST -d \

'{
     "name": "Volume banded rate card plan",
     "developer":null,
     "developerCategory":null,
     "currency": {
      "id" : "usd"
     },     
     "frequencyDuration": "30",
     "description": "Volume banded rate card plan",
     "displayName" : "Volume banded rate card plan",
     "frequencyDuration": "30",
     "frequencyDurationType": "DAY",
     "earlyTerminationFee": "10",
     "monetizationPackage": {
      "id": "location"
     },
     "organization": {
      "id": "{org_name}"
     },    
     "paymentDueDays": "30",
     "prorate": "false",
     "published": "true",
     "ratePlanDetails": [
     {
      "currency": {
       "id" : "usd"
      },
      "aggregateStandardCounters": true,
      "paymentDueDays": "30",
      "duration": "1",
      "durationType": "MONTH",
      "meteringType": "VOLUME",
      "organization": {
       "id": "{org_name}"
      },      
      "ratePlanRates": [
      {
       "type": "RATECARD",
       "rate": "0.15",
       "startUnit": "0",
       "endUnit": "1000"
      },
      {
       "type": "RATECARD",
       "rate": "0.10",
       "startUnit": "1000"      
      }
      ],     
     "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" \
-u email:password

Specifying a bundled charging model

In a bundled charging model, the developer pays (up-front) for a "bundle" of transactions (or for a bundle based on a custom attribute such as the number of bytes transmitted). You specify a rate for each bundle and an aggregation bases, that is, a period of time in which the developer can use the bundle.

For example, suppose you set up two bundles, where the first bundle size is to 1-to-1000 transactions, and a second bundle size is 1001-to-2000 transactions. The rate is $50 for the first bundle and $40 for the second bundle, and the aggregation basis is 1. If the developer purchases a rate card plan for the first bundle, they pay $50 (up front) for 1000 transactions in a month. The developer is charged the set amount whether or not the bundle is entirely used. After the aggregation period ends, the plan expires. If the developer wants to use the bundle again, they must purchase the plan (and the bundle) again.

What you specify in the rate plan details is essentially the same as what you specify in the rate plan details for the volume banded charging model. The differences are as follows:

• Each rate plan you specify is for a bundle (rather than for a volume band).
• You must specify an upper limit for the last bundle, unless you want to charge the developer a fixed amount for unlimited transactions in the last bundle.

See Rate plan details configuration settings for a complete list of rate plan detail options.

For example, the following creates a rate card plan with a bundled charging model. The rate is set at $50 for the first bundle (up to 1000 transactions), and $40 for the second bundle (more than 1000 and up to 2000 transactions). The aggregation basis is 1 month. Payment is due in 30 days.

curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Bundled rate plan",
     "developer":null,
     "developerCategory":null,
     "currency": {
      "id" : "usd"
     },    
     "frequencyDuration": "30",
     "description": "Bundled rate plan",
     "displayName" : "Bundled rate plan",
     "frequencyDurationType": "DAY",
     "earlyTerminationFee": "10",
     "monetizationPackage": {
      "id": "location"
     },
     "organization": {
      "id": "{org_name}"
     },    
     "paymentDueDays": "30",
     "prorate": "true",
     "published": "true",
     "ratePlanDetails": [
     {
      "currency": {
       "id" : "usd"
      },
      "aggregateStandardCounters": true,
      "paymentDueDays": "30",
      "duration": "1",
      "durationType": "MONTH",
      "meteringType": "STAIR_STEP",
      "organization": {
       "id": "{org_name}"
      },
      "ratePlanRates": [
      {
       "type": "RATECARD",
       "rate": "50",
       "startUnit": "0",
       "endUnit": "1000"
      },
      {
       "type": "RATECARD",
       "rate": "40",
       "startUnit": "1000",
       "endUnit": "2000"
      }
      ],
     "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" \
-u email:password

Specifying a freemium plan for individual products using the API

In a rate card plan, you can set up a freemium plan for an individual product (rather than for an API package). A freemium plan offers developers free use of an API product over a period of time or based on the amount of use.

When you set up a freemium plan for an API product, you specify in the rate card plan details the period in which the developer can use the resources provided by the API product free of charge. The period can be based on one of the following:

• Duration, that is, the time between an effective date and an end date.
• Quantity, such as the number of transactions involving the API product or the volume pertaining to a custom attribute recorded in the transaction recording policy.

If the freemium period is based on quantity, specify it as a number of freemium units. For example, the following creates a rate card plan with a freemium plan based on a volume of 5000 units (the freemium-related specifications are highlighted.)

curl -H "Content-Type:application/json" -X POST -d \
'{
      "name": "Flat rate card plan with freemium period",
      "developer":null,
      "developerCategory":null,      
      "advance": "false",
      "currency": {
       "id" : "usd"
      },     
      "description": "Flat rate card plan with freemium period",
      "displayName" : "Flat rate card plan with freemium period",
      "frequencyDuration": "30",
      "frequencyDurationType": "DAY",
      "earlyTerminationFee": "10",     
      "monetizationPackage": {
       "id": "location"
      },
      "organization": {
       "id": "myorg"
      },
      "paymentDueDays": "30",
      "prorate": "false",
      "published": "false",
      "ratePlanDetails": [
      {
       "currency": {
       "aggregateFreemiumCounters" : true,
       "aggregateStandardCounters" : true,
        "id" : "usd"
       },
       "product" : {
        "id" : "location",
        "displayName":"Location"
       },
       "paymentDueDays": "30",      
       "meteringType": "UNIT",
       "organization": {
        "id": "myorg"
       },
       "ratePlanRates": [
        {
         "type": "RATECARD",
         "rate": "0.10",
         "startUnit": "0"       
        }      
       ],
      "freemiumUnit": "5000",
      "freemiumDuration": "0",
      "freemiumDurationType": "DAY",
      "ratingParameterUnit":"MB",
      "customPaymentTerm": "false",
      "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" \
-u email:password