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, which can be one of the following:

  • Flat rate. In this model, the developer is charged a fixed rate for each transaction.
  • Volume banded. In this model, the developer is charged a variable rate depending on the volume of transactions.
  • Bundles. In this model, the developer is charged a set amount (up-front) for each bundle of transactions. The developer is charged the set amount whether or not the bundle is entirely used.

You also need to specify the 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.

Toolbox

You can specify rate card plan details using the management UI or monetization API. If you use the UI, you specify the details in the Generic Rate Card window.

If you use the API, you specify rate card plan details in the ratePlanDetails property within the request body in a call to the /organizations/{org_name}/monetization-packages/{package_id}/rate-plans resource (when you create the rate plan).

Specifying rate card plan details using the UI

  1. Select Rate Card. This link appears below the Specific or Generic field when you select Rate Card as the rate plan type.

    This opens the Generic Rate Card window.

  2. Set up a freemium plan for an API product. A freemium plan offers developers free use of an API product over a period of time or based on the amount of use.

    A freemium plan is optional. By default, the rate plan is not a freemium plan. You can set up a freemium plan for an API product only for a product-specific plan (that is, you specified "Product-Specific Plans" in the "Specific or Generic" field.

    Enter the following information:

    Field Description
    Freemium Product?

    The extent of the free period. Select one of the following radio buttons:

    • By Quantity. The free period is based on a quantity specified in the Volume field.
    • By Duration. The fee period is based on a time interval specified in the Freemium Duration field.
    • Whichever comes first. The free period ends when either the quantity in the Volume field or the time interval in the Freemium Duration field is reached, whichever happens first.
    • No. This is not a freemium plan. This is the default.
    Freemium Volume

    The volume of transactions (or volume pertaining to a custom attribute recorded in the transaction recording policy) for which the developer is not charged. The volume is measured for the API product. Enter a volume number, such as 5000. This means that when the developer starts the plan, he is not charged for the first 5000 transactions (or for the first 5000 uses of a custom attribute-related item). This field is enabled only if you select "By Quantity" or "Whichever comes first" in the "Freemium Product?" field.

    Freemium Duration

    The time interval during which the developer is not charged. Enter a number and select a time period, for example, 1 Month. This means that the developer is not charged for 1 month. This field is enabled only if you select "By Duration" or "Whichever comes first" in the "freemium Product?" field.

  3. Select one of the following charging models:
    • Flat Rate. In this model, the developer is charged a fixed rate for each transaction.
    • Volume Banded. In this model, the developer is charged a variable rate depending on the volume of transactions.
    • Bundles. In this model, the developer is charged a set amount (up-front) for each bundle of transactions. The developer is charged the set amount whether or not the bundle is entirely used.

     

    For the flat rate model: Enter the following information in the Pricing section of the Generic Rate Card window:

    Field Description
    Operator (or Organization)

    The name of your organization. This field is preset using the Operator (or Organization) field value in the organization profile.

    Country

    The country of operation of your organization. This field is preset using the Country field value in the organization profile.

    Flat Rate

    The rate charged for each transaction. Enter a decimal number (with up to four decimal places). For example, if you enter 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).

    For the volume banded model: The Generic Rate Card window displays additional fields that you use to specify a basis for aggregation and to specify "volume bands", that is, ranges of transaction volume for which you can apply different rates.

    This type of plan is usually set up to encourage developers to generate higher volumes by offering discounted rates for higher volume bands.

    Enter the following information in the Generic Rate Card window:

    Field Description
    Aggregation Basis

    The period of time over which the volume of transactions (or custom attribute-related volume) is aggregated. The aggregated volume is used to identify the volume band and the rate to apply to each transaction. Select a number of months (1-12 months).

    Volume Bands

    One or more ranges of transaction (or customer attribute-based) volume (each range is a "volume band"). Each volume band can be assigned a rate (you set this rate in the Volume Bands field of the Pricing section.) The rate is applied to all transactions in the applicable volume band. Specify the upper limit of the first band, for example, up to 1000 (the lower limit is preset to greater than 0). Click + to add a second band, for example, greater than 1000 up to 2000. Click + to add more bands. You can leave the upper limit of the final band empty to indicate all transactions above this level.

    Pricing
    Operator (or Organization)

    The name of your organization. This field is preset using the Operator (or Organization) field value in the Organization Profile.

    Country

    The country of operation of your organization. This field is preset using the Country field value in the Organization Profile.

    Currency

    The "base" or accounting currency that your organization uses. This field is preset using the Currency field value in the Organization Profile, but it can be changed here.

    Volume Bands

    The rate for a volume band. You specify a rate for each volume band. Enter a decimal number for each band (with up to four decimal places). For example, if you specify two volume bands in the Volume Band section (>0-1000, and 1000 and above), you might enter 0.15 for the >0-1000 volume band, and 0.10 for the 1000 and above volume band. If the selected currency is U.S. dollars, the rate for the first 1000 transactions is $0.15 for each transaction, and for more than 1000 transactions, the rate is $0.10 for each transaction.

    For the bundled model: The Generic Rate Card window displays additional fields that you use to specify a basis for aggregation (the period of time in which the developer can use the bundle of transactions) and to specify bundle-related information such as the size of a bundle.

    Enter the following information in the Generic Rate Card window:

    Field Description
    Aggregation Basis

    The period of time in which the developer can use the bundle of transactions (or use a custom attribute-based bundle). Select a number of months (1-12 months). After this period, the plan expires and the developer must purchase the plan (and bundles) again.

    Bundle Size

    The number of transactions in a bundle (or a number related to a custom attribute such as a total number of bytes transmitted in a bundle). Each bundle can be assigned a price (you set this price in the Bundle Size field of the Pricing section.) The price applies to the entire bundle. Specify the upper limit of the first bundle, for example, up to 1000 (the lower limit is preset to greater than 0). Click + to add a second bundle, for example, greater than 1000 up to 2000. Click + to add more bundles. 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.

    Pricing
    Operator (or Organization)

    The name of your organization. This field is preset using the Operator (or Organization) field value in the Organization Profile.

    Country

    The country of operation of your organization. This field is preset using the Country field value in the Organization Profile.

    Currency

    The "base" or accounting currency that your organization uses. This field is preset using the Currency field value in the Organization Profile, but it can be changed here.

    Bundle Size (price)

    The price for a bundle. You specify a price for each bundle. Enter a decimal number (with up to four decimal places). For example, if you specify two bundles in the Bundle Size section (greater than 0 up to 1000, and greater than 1000 up to 2000), you might enter 50 for the greater than 0 up to 1000 bundle, and 40 for the greater than 1000 up to 2000 bundle. If the selected currency is U.S. dollars, the price for the first bundle is $50, and for the second bundle, the price is $40. The developer is charged the applicable bundle price irrespective of how many transactions they use within the bundle (that is, the developer is charged the bundle price as soon as the first transaction in the bundle is completed.)

  4. Click Apply and Close to save the rate card details and return to the Standard Rate Plan window.

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 myname:mypass

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.

    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 revenue share-related 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 myname:mypass

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, he pays $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, he 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:

  • Specify a metering type of STAIR_STEP. This indicates that the rate is based on the bundle size.
  • The duration and duration type together specify the period of time over which the developer can use a bundle (rather than the period of time used to aggregate the volume of transactions).
  • 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. (The revenue share-related details are highlighted.)

$ 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 myname:mypass

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.

By default, a rate card plan is not a freemium plan. You can set up a freemium plan for an API product only for a product-specific plan.

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 myname:mypass

Get help

For help, see Apigee Customer Support.

Next steps

After you create the rate plan and provide rate plan details, you can publish the plan or save it as a draft. See Publish rate plans for more information.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)