You're viewing **Apigee Edge** documentation. [Go to the **Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/reference/limits). info ## Introduction In some cases, you may need transaction counters to be based on a variable or custom value. For example, you may need to: - Charge developers a variable amount based on a value provided in the message of an API call. For example, you may want to charge app developers based on the number of bytes transmitted in the API request. - Bundle multiple API calls into a single transaction. Using rate plans with custom attributes, you can identify a value in the message of an API call that acts as counter, and that is used to calculate transaction counts and charges. The following rate plans with custom attributes are supported: - Rate card with custom attribute - Adjustable notification with custom attribute You can set a maximum of ten custom attributes per rate plan. ### Understanding custom attribute calculations How the custom attribute value gets factored into the rate plan transaction counts and charges depends on the charging model, as summarized in the following table. | 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: - The developer gets the "over" amount free. - The developer app is blocked from making further calls to the API until the plan period resets. See [When are recurring fees charged and bundle plans reset?](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details#reset) for details on when plans are reset. | | 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. The rate for that next bundle, if any, is charged. If the last bundle has a limit (is not "unlimited") and a transaction exceeds that limit, two things happen: - The developer gets the "over" amount free. - The developer app is blocked from making further calls to the API until the plan period resets. See [When are recurring fees charged and bundle plans reset?](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details#reset) for details on when plans are reset. | | Adjustable notifications | For adjustable notification, the following calculation occurs: `custom attribute number = amount added to transaction count` For example, if the custom attribute number in the message is 10, then 10 is added to the total number of transactions. | ### Where the rate plan gets the custom attribute value The Transaction Recording Policy (on the API product bundle) tells monetization where to look in the message for the custom attribute value. You define the custom attribute in the Custom Attributes section of the transaction recording policy for the API product bundle. Then, you can select that custom attribute in the rate plan---after you create an API product bundle that contains the transaction recording policy with the custom attribute defined. Here is the high-level flow: 1. Define the custom attributes when [adding an API product](https://docs.apigee.com/api-platform/publish/create-api-products#add). 2. Create an API product bundle that contains the product. In the transaction recording policy for the API product bundle, add the custom attributes that will be used to define rate plans. 3. [Create a rate plan](https://docs.apigee.com/api-platform/monetization/create-rate-plans#create) of type rate card or adjustable notification for the API product bundle and specify a **custom rating parameter**. The following figure shows the relationship between the custom attribute defined in the transaction recording policy and the rate card plan configuration. The adjustable notification with custom attribute rate plan relationship is similar, though the volume-banded value is not applicable. ![](https://docs.apigee.com/static/api-platform/images/custom-attributes.png) > [!NOTE] > **Note:** 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. ### How to generate the custom attribute value in the message The transaction recording policy can look for the custom attribute value in several places, such as the response header, the response body, or the 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 examples showing you how to add a **response header** with its numeric value to the message. In both cases, we'll use the [Assign Message policy](https://docs.apigee.com/api-platform/reference/policies/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: ``` Assign Message 1
{client.received.content.length}
 true ``` #### 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. For example, if you include a custom attribute called `apprating` on each developer app, as follows: ![](https://docs.apigee.com/static/api-platform/images/app_custom_attribute2.png) When using the Verify API Key policy (which is required for monetization), 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: ``` Assign Message 1
{verifyapikey.Verify-API-Key-1.apprating}
 true ``` ## Setting up the rate plan Other than the custom attribute setup described above, the rate plan is set up in the same way as you would normally (for rate plans without custom attributes), but must adhere to the following requirements. > [!WARNING] > **Warning:** **Requirements for setting up a rate plan with custom > attributes** : > > - Specify the custom attribute value in the message as: > - Positive whole or decimal (up to four decimal places) value. Negative values are not allowed. > - String type; other data types are not supported. Header values are always strings, but flow variables must be specified as a string. > - Specify a custom attribute on an API product's transaction recording policy **before** you create the API package. (Learn how to specify transaction policy custom attributes in [Create a transaction > recording policy](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy).) > - Make sure the product has at least one resource defined, even if it's \*\*. > - The API package can have one or more API products. > - The custom attribute name `VOLUME` is reserved. Don't use it as a custom attribute name. ## Configuring rate card plan with custom attribute using the UI Configure rate card plans with custom attributes using the Edge UI or Classic Edge UI, as described in the following sections. ### Edge To configure a rate card plan with custom attributes using the Edge UI: 1. Define the custom attributes when [adding an API product](https://docs.apigee.com/api-platform/publish/create-api-products#add). 2. Create an API product bundle that contains the product. See [Create API product bundles](https://docs.apigee.com/api-platform/monetization/create-api-packages). In the transaction recording policy for the API product bundle, 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](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy). 3. [Create a rate plan](https://docs.apigee.com/api-platform/monetization/create-rate-plans#create) for the API product bundle and specify a **custom rating parameter**. For more information, see [Configure rate card plan details using the UI](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details#ui). ### Classic Edge (Private Cloud) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. Use the following steps to create a Rate Card with Custom Attribute plan using the Classic Edge UI: 1. In an API 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](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy). Do this for each API product you want to include in the API package. 2. Once the API 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](https://docs.apigee.com/api-platform/monetization/create-api-packages). 3. Create a rate plan for the API package, selecting the rate plan type of **Rate Card with Custom Attribute**. 4. Click the **Rate Card** link. This opens the Rate Card window. ![](https://docs.apigee.com/static/api-platform/images/rate-card-with-attribute.png) 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. Optionally, set up a freemium plan as described in [Specify rate card plan details](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details). 7. Set up a charging model as described in [Specify rate card plan details](https://docs.apigee.com/api-platform/monetization/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](https://docs.apigee.com/api-platform/monetization/specify-rate-card-custom-attribute-details#calculations) for more. 8. Click **Save Draft** . Publish the plan only when you're absolutely sure it's final. See [Publish rate plans](https://docs.apigee.com/api-platform/monetization/publish-rate-plans) for information about setting the Publish Date and publishing the plan. For more information, see [Specifying rate card plan details using the UI](https://docs.apigee.com/api-platform/monetization/specify-rate-card-plan-details#specifyingratecardplandetailsusingtheui). ## Configuring an adjustable notification plan with custom attributes using the UI Configure adjustable notification plans with custom attributes, as described below. ### Edge To configure a rate card plan with custom attributes using the Edge UI: 1. Define the custom attributes when [adding an API product](https://docs.apigee.com/api-platform/publish/create-api-products#add). 2. Create an API product bundle that contains the product. See [Create API product bundles](https://docs.apigee.com/api-platform/monetization/create-api-packages). In the transaction recording policy for the API product bundle, 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](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy). 3. [Create a rate plan](https://docs.apigee.com/api-platform/monetization/create-rate-plans#create) for the API product bundle and specify a **custom rating parameter**. For more information, see [Configure an adjustable notification plan using the UI](https://docs.apigee.com/api-platform/monetization/specifying-adjustable-notification-plan-details#ui). ### Classic Edge (Private Cloud) > [!NOTE] > **Note:** The Classic Edge UI is available with Edge for Private Cloud only. To configure a rate card plan with custom attributes using the Classic Edge UI: 1. In an API 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](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy). Do this for each API product you want to include in the API package. 2. Once the API 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](https://docs.apigee.com/api-platform/monetization/create-api-packages). 3. Create a rate plan for the API package, selecting the rate plan type of **Adjustable Notification with Custom Attribute**. 4. Click the **Details** link. This opens the Adjustable Notification window. ![](https://docs.apigee.com/static/api-platform/images/anrp-with-attribute.png) 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's total number of transactions is calculated on the value of the selected custom attribute within each transaction. 6. Set the **Aggregation Basis** to the period of time over which the volume of transactions is aggregated. Select a number between 1 and 24 months. This value defaults to 1 month. 7. Click **Apply and Close**. 8. Click **Save Draft** . Publish the plan only when you're absolutely sure it's final. See [Publish rate plans](https://docs.apigee.com/api-platform/monetization/publish-rate-plans) for information about setting the Publish Date and publishing the plan. For more information, see [Specifying Adjustable notification plan details using the UI](https://docs.apigee.com/api-platform/monetization/specifying-adjustable-notification-plan-details#specifyingadjustablenotificationplandetailsusingtheui). ## Specifying details for a rate plan with custom attributes using the API Perform the following prerequisite steps: 1. In an API 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](https://docs.apigee.com/api-platform/monetization/create-transaction-recording-policy). Do this for each API product you want to include in the API package. 2. Once the API 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](https://docs.apigee.com/api-platform/monetization/create-api-packages). Next, you use the API to create the rate plan. You specify details for a rate 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](https://docs.apigee.com/api-platform/monetization/create-rate-plans#rateplandetails) for a complete list of rate plan detail options. For example, the following creates a Rate Card with Custom Attribute plan based on a custom attribute named `messageSize` (see items in **bold**). ``` $ 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":"messageSize", "ratingParameterUnit":"MB", "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", "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 ``` The following creates an Adjustable Notification with Custom Attribute rate plan based on a custom attribute named `messageSize` (see item in **bold**). ``` $ curl -H "Content-Type:application/json" -X POST -d \ '{ "name": "AdjustableNotification", "displayName": "Custom attribute-based adjustable notification plan", "description": "Custom attribute-based adjustable notification plan", "published": "true", "organization": { "id": "myorg" }, "startDate": "2016-04-15 00:00:00", "type": "STANDARD", "monetizationPackage": { "id": "p1", "name": "test" }, "currency": { "id" : "usd", "name" : "USD" }, "ratePlanDetails": [ { "type": "USAGE_TARGET", "meteringType": "DEV_SPECIFIC", "duration": 1, "durationType": "MONTH", "ratingParameter": "messageSize", "ratingParameterUnit": "MB", "organization": { "id": "myorg" }, "currency": { "id": "usd", "name": "USD" } } ] }' \ "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/monetization-packages/p1/rate-plans" \ -u email:password ```