Send Docs Feedback

Specify rate card with custom attribute

What if you wanted to charge developers a variable amount based on some type of number in the message of an API call? For example, say you wanted to charge app developers based number of bytes transmitted in the API request payload.

That's what the "Rate card with custom attribute" rate plan is for. It identifies a number in the message (must be a whole number), which acts as counter that is used to calculate transaction counts and charges, whether you're using a Flat Rate, Volume Banded, or Bundles as the charging model.

Calculations

Here's how the custom attribute number gets factored into the rate plan charges.

Rate card charging model Custom attribute calculation
Flat Rate and Volume Banded

custom attribute number * rate = charge to developer

For a Flat Rate, the custom attribute number becomes the number of transactions that are multiplied against the rate. For Volume Banded, the number of transactions in a band is incremented by the custom attribute number, and the developer is charged for that number of transactions. For example, If a custom attribute value in the message is 10, then the developer is charged for 10 transactions, and 10 transactions are added to the current band count. If the developer had only 6 transactions remaining in the current band, 6 is multiplied by the rate for that band. The remaining 4 go into the next band and are multiplied by that band's rate.

In a Volume Banded plan, if the last volume band has a limit (is not "unlimited") and a transaction exceeds that limit, two things happen:

Bundles

Since bundles are charged by the group, not by the transaction, the following calculation occurs:

custom attribute number = amount added to bundle count

For example, if the custom attribute number in the message is 10, then 10 is added to the number of transactions used in the bundle. If the developer had only 6 transactions remaining in the current bundle, then that bundle is filled and the next bundle count is incremented by 4.

If the last bundle has a limit (is not "unlimited") and a transaction exceeds that limit, two things happen:

Where the rate plan gets the attribute number

The Transaction Recording Policy (on the API product) tells monetization where to look in the message for the custom attribute number. In the transaction recording policy's Custom Attributes section, you'll specify that custom attribute.

Then, you can select that custom attribute in the rate plan—after you create a package that contains the product (the one that contains the transaction recording policy you just added the custom attribute to). Here's the flow:

  1. Add custom attribute to transaction recording policy
  2. Create a package with the product in it
  3. Create a "Rate Card with Custom Attribute" rate plan

This diagram shows the relationship between the transaction recording policy and the rate plan configuration:

You can use the same name for the variable in the message itself, the variable name in the transaction recording policy, and even the static attribute on an API product.

The Rating Unit label on the rate plan appears in the developer portal, along with the custom attribute name, letting the developer know what she's being charged for. Here's an example of what a developer would see in the developer portal when purchasing a rate plan:

But how does the custom attribute number get generated in the message to begin with? Read on.

Generating the custom attribute number in the message

The transaction recording policy can look for the custom attribute number in a few places, such as the response header, the response body, or a few predefined flow variables in the response. (The request isn't available, because a transaction isn't official until you get a successful response.) Following are a couple of examples showing how you could add a response header with its numeric value to the message. In both cases, we'll use the Assign Message policy in conjunction with variables.

Adding request payload size to the response header

In each message request, there's a client.received.content.length variable that contains the number of bytes in the request payload. By attaching an Assign Message policy to the Proxy Endpoint response, we can generate a response header called "messagesize" that contains the length value:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="messagesize">{client.received.content.length}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Adding an app custom attribute value to the header

In much the same way, we can generate a header with the value of a custom attribute on an app. Say you include a custom attribute called "apprating" on each developer app, like this:

When using the Verify API Key policy (which you need to with monetization anyway), this value is stored in a variable called verifyapikey.{policy_name}.apprating. Using the Assign Message policy attached to the Proxy Endpoint response, you could generate a header called "apprating" that contains the app's "apprating" value:

<AssignMessage async="false" continueOnError="false" enabled="true" name="Assign-Message-1">
    <DisplayName>Assign Message 1</DisplayName>
    <Set>
        <Headers>
          <Header name="apprating">{verifyapikey.Verify-API-Key-1.apprating}</Header> 
        </Headers>  
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Rate plan setup

Other than the custom attribute setup described above, the rate plan is the same as the rate card type. In particular, you need to provide the same additional details about the charging model (for example, whether developers are charged at a fixed rate or a variable rate) and pricing (such as the rate charged).

Requirements for setting up a "rate card with custom attribute" plan:

  • The custom attribute number in the message must be a whole number (no decimals or negatives).
  • Specify a custom attribute on a product's transaction recording policy before you create a package. (Learn how to specify transaction policy custom attributes in Create a transaction recording policy.)
  • Make sure the product has at least one resource defined, even if it's **.
  • The API package must have one product.
  • The custom attribute name "VOLUME" is reserved. Don't use it as a custom attribute.

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 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 details for a rate card plan with custom attributes using the UI

Use the following steps to create a rate plan based on custom attributes.

  1. In a product's transaction recording policy, add the custom attributes that will be used to define rate plans. For details, see the introduction in this topic, as well as Create a transaction recording policy. Do this for each product you want to include in the package.
  2. Once the products and transaction recording policies are configured exactly the way you want them, create an API package that contains the product. See Create API packages.
  3. Create a rate plan for the package, selecting the rate plan type of Rate Card with Custom Attribute.
  4. Click the Rate Card link. This opens the Rate Card window.

    Notice that fields for Custom Attribute and Rating Unit appear in the Rate Card window.

  5. Select a custom attribute in the Custom Attribute drop-down menu. The menu lists custom attributes created for the product in a transaction recording policy. The developer is charged based on the value of the selected custom attribute within each transaction.
    (Attribute value * rate = charge to developer)
  6. Enter a name in the Rating Unit field, such as Bytes, MB, or whatever the custom attribute number represents. Developers see this when they purchase the plan in the developer portal.
  7. Optionally, set up a freemium plan as described in Specify rate card plan details .
  8. Set up a charging model as described in Specify rate card plan details. Note, however, that for the Rate Card with Custom Attribute rate plan type, the charging model is based on the custom attribute you select. For example, if you choose Flat Rate as the charging model, the developer is charged a fixed rate based on the custom attribute, such as the number of bytes transmitted in each transaction (not a fixed rate for each transaction). See Calculations for more.

Specifying details for a rate card plan with custom attributes using the API

See the previous section for the steps that need to happen before creating a rate plan. Once those steps are complete, use the API call to create a rate plan.

You specify details for a rate card plan with custom attributes 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. In the details, you specify a rating parameter value that identifies the name of the custom attribute. You can also specify a rating parameter value that aggregates the custom attribute over a specified time interval.

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

For example, the following creates a rate card plan based on a custom attribute named user (the custom attribute-related specifications are highlighted.)

$ curl -H "Content-Type:application/json" -X POST -d \
'{
   "name": "Custom attribute-based rate card plan",
   "developer":null,
   "developerCategory":null,
   "currency": {
     "id" : "usd"
     },     
   "description": "Custom attribute-based rate card plan",
   "displayName" : "Custom attribute-based rate card plan",
   "frequencyDuration": "1",
   "frequencyDurationType": "MONTH",
   "earlyTerminationFee": "10",
   "monetizationPackage": {
      "id": "location"
        },
      "organization": {
       "id": "{org_name}"
      },    
   "paymentDueDays": "30",
   "prorate": "false",
   "published": "false",     
   "ratePlanDetails":[
      {
        "currency":{
           "id":"usd"
        },
      "duration":1,
      "durationType":"MONTH",
      "meteringType":"VOLUME",
      "paymentDueDays":"30",
      "ratingParameter":"user",
      "organization":{
         "id":"{org_name}"
      },
      "ratePlanRates":[
         {
           "rate":0.15,
           "startUnit":0,
           "type":"RATECARD",
           "endUnit":1000
         },
         {
           "rate":0.1,
           "startUnit":1000,
           "type":"RATECARD",
           "endUnit":null
         }
      ],
      "freemiumUnit":0,
      "freemiumDuration":0,
      "freemiumDurationType":"MONTH",
      "type":"RATECARD",
      "product":{
         "customAtt1Name": "user",
         "id":"location",
         "displayName":"Location"
      },
      "ratingParameterUnit":"MB",
      "customPaymentTerm":false
      }
    ],
    "freemiumUnit":0,
    "freemiumDuration":0,
    "freemiumDurationType":"MONTH",
    "contractDuration":"1",
    "contractDurationType":"YEAR", 
    "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

Next steps

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

Help or comments?