You're viewing Apigee Edge documentation.
Go to the
Apigee X documentation. info
Introduction
In a revenue share plan, the API provider shares with the developer a percentage of the revenue generated from each transaction (based on the gross or net price of a transaction). When you create a revenue share plan you need to indicate a sharing model, which can be either fixed or flexible, and a pricing basis (such as whether the revenue share is based on the gross or net price of a transaction). You set the gross or net price for the transaction when you create the transaction recording policy.
In the fixed sharing model, you share with the developer a fixed percentage of the revenue generated from each transaction (based on the gross or net price of a transaction). In the flexible sharing model, you share with the developer a variable percentage of the revenue. The revenue share depends on the revenue generated over a period of time. The percentage used in the revenue share calculation can vary based on the amount of revenue generated by transactions.
Specifying revenue share plan details using the UI
Configure revenue share plans, as described below.
Edge
To configure a revenue share plan using the Edge UI, when creating or editing a rate plan, select the Revenue Share or Rate Card and Revenue Share rate plan type and in the Revenue share section configure the following information:
| Field | Description |
| Calculation model | Select one of the following pricing types:
|
| Calculation frequency | Period of time over which the volume of transactions (or custom attribute-related volume) is calculated. Select a number of months (1-24 months). |
| Sharing model | Select one of the following revenue share models:
|
| Fixed revenue share | For the fixed sharing model, specifies the percentage used to calculate the revenue share. Enter a decimal number (with up to four decimal places). For example, if you enter 80.5555, the revenue share is 80.5555%, that is, as an API provider, you pay the developer 80.5555% of the price charged for each transaction. |
| Revenue share bands | For the flexible sharing model, one or more ranges of transaction revenue (each range is a "revenue band"). Each revenue band can be assigned a revenue share percentage. Transactions are aggregated over the aggregation basis to calculate the total revenue and the revenue band for the transaction. The revenue share percentage applied to each transaction depends on its revenue band. Specify the upper limit of the first band, for example, up to 1000 (the lower limit is preset to greater than 0). Click +New to add additional bands. Leave the upper limit of the final band empty to indicate all transactions after the aggregate revenue has gone above this level. For example, if you specify two revenue bands in the Revenue Band section (>0-1000, and 1000 and above), you might enter 80.5555 for the >0-1000 revenue band, and 90.5 for the 1000 and above revenue band. Also assume the currency is in U.S. dollars. Then for the transactions that generate up to $1000 in revenue, the revenue share is 80.5555% of the transaction price, and for the transactions that generate more than $1000 in revenue, the revenue share is 90.5% of the transaction price. |
Classic Edge (Private Cloud)
To configure revenue share plans using the Classic Edge UI:
- Follow the steps to create a rate plan.
- Select Revenue Share in the Rate Plan Type drop-down to configure the revenue model.
- If the selected API package includes multiple API products, select one of the following options:
Note: If the API package includes a single API product, you can skip this step.
- Product-Specific Plans to configure rate plan details for each API product individually.
- Generic Plan for All Products to configure rate plan details for all API products.
- Click Revenue Share for the generic rate plan or for each API product-specific rate plan.
Note: When configuring API product-specific plans, you will need to configure a revenue share plan for each API product individually.
The Revenue Share window opens.
- Select one of the following sharing models:
- Fixed: In this model, the API provider shares with the developer a fixed percentage of the revenue generated from each transaction (based on the gross or net price of a transaction).
- Flexible: In this model, the API provider shares with the developer a variable percentage of the revenue. The revenue share depends on the revenue generated over a period of time. The percentage used in the revenue share calculation can vary based on the amount of revenue generated by transactions.
For the fixed sharing model:
If you select the fixed sharing model, enter the following information in the Pricing section of the Generic Revenue Share 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.
Currency The "base" or accounting currency that your company uses. This field is preset using the Currency field value in the organization profile.
Pricing Type The basis of the revenue share. Select Gross or Net. If you select Gross, the revenue share is based on a percentage of the gross price of a transaction. If you select Net, the revenue share is based on a percentage of the net price of a transaction. Note: You set the gross or net price for the transaction when you create the transaction recording policy.
Fixed Share % The percentage used to calculate the revenue share. Enter a decimal number (with up to four decimal places). For example, if you enter 80.5555, the revenue share is 80.5555%, that is, as an API provider, you pay the developer 80.5555% of the price charged for each transaction.
For the flexible sharing model:
If you select the flexible sharing model, you'll notice that Generic Revenue Share window displays additional fields. You use these fields to specify a basis for aggregation and to specify "revenue bands", that is, ranges of transaction-generated revenue for which you can apply different revenue share percentages.
Enter the following information in the Generic Revenue Share window:
Field Description Aggregation Basis The period of time over which revenue is aggregated. The aggregated revenue is used to calculate the revenue band for each transaction (and the applicable revenue share percentage). Select a number of months (between 1 and 12).
Revenue Bands One or more ranges of transaction revenue (each range is a "revenue band"). Each revenue band can be assigned a revenue share percentage (you set this percentage in the Revenue Bands field of the Pricing section.) Transactions are aggregated over the aggregation basis to calculate the total revenue and the revenue band for the transaction. The revenue share percentage applied to each transaction depends on its revenue 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 and up to 2000. Click + to add more bands. You can leave the upper limit of the final band empty to indicate all transactions after the aggregate revenue has gone 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.
Pricing Type The basis of the revenue share. Select Gross or Net. If you select Gross, the revenue share is based on a percentage of the gross price of a transaction. If you select Net, the revenue share is based on a percentage of the net price of a transaction. Note: You set the gross or net price for the transaction when you create the transaction recording policy.
Share % for Revenue Bands The percentage used to calculate the revenue share for the transactions in each revenue band. You specify a percentage for each band. Enter a decimal number (with up to four decimal places). For example, if you specify two revenue bands in the Revenue Band section (>0-1000, and 1000 and above), you might enter 80.5555 for the >0-1000 revenue band, and 90.5 for the 1000 and above revenue band. Also assume the currency is in U.S. dollars. Then for the transactions that generate up to $1000 in revenue, the revenue share is 80.5555% of the transaction price, and for the transactions that generate more than $1000 in revenue, the revenue share is 90.5% of the transaction price.
- Click Apply and Close to save the revenue share details and return to the Standard Rate Plan window.
- For API product-specific rate plans, configure the rate plan details for additional API products, as required.
Specifying revenue share plan details using the API
You specify revenue share 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 sharing model you choose:
fixed or flexible.
Specifying revenue share plan details for a fixed sharing model
To implement the fixed sharing model, you specify the following in the rate plan details:
- A rating parameter that indicates that the rate plan is based on transactions
(
VOLUME).VOLUMEis the default. - A metering type (
UNIT) that indicates that the revenue share is fixed per unit (that is, it’s not based on the volume of transactions, as is the case for the flexible sharing model). - The revenue type (
GROSSorNET). This indicates whether the revenue share is based on the gross or net price of a transaction. - 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 revenue share is calculated. Because the sharing model is based on a fixed rate, you only specify one rate plan rate.
See Configuration properties for rate plan details for a complete list of rate plan detail properties.
In the rate plan rate, you specify:
- The type of the rate plan rate (
REVSHARE). - The percentage used to calculate the revenue share. For example, if you specify 80.5555, the revenue share is 80.5555%, that is, as an API provider, you pay the developer 80.5555% of the price charged for each transaction (or if based on a custom attribute such as the number of bytes transmitted in a transaction, you pay the developer 80.5555% of the price charged 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 Configuration properties for rate plans for a complete list of rate plan properties.
For example, the following creates a revenue share plan with a fixed sharing model. The revenue share percentage is 80.5555%. The revenue share is based on the net price of a transaction. The contract is effective September 15, 2013, and payment is due in 30 days. (The revenue share-related details are highlighted.)
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"name": "Fixed share plan",
"developer":null,
"developerCategory":null,
"advance": false,
"currency": {
"id": "usd"
},
"description": "Fixed share plan",
"displayName": "Fixed share plan",
"earlyTerminationFee": 10,
"monetizationPackage": {
"id": "location"
},
"organization": {
"id": "{org_name}"
},
"paymentDueDays": "30",
"prorate": false,
"published": true,
"ratePlanDetails": [
{
"aggregateStandardCounters": true,
"currency": {
"id": "usd"
},
"duration": 1,
"durationType": "MONTH",
"meteringType": "UNIT",
"organization": {
"id": "{org_name}"
},
"paymentDueDays": "30",
"ratePlanRates": [
{
"revshare": 80.8555,
"startUnit": 0,
"type": "REVSHARE"
}
],
"ratingParameter": "VOLUME",
"revenueType": "NET",
"type": "REVSHARE"
}
],
"recurringStartUnit": 1,
"recurringType": "CALENDAR",
"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 response should look like this this (only part of the response is shown):
{ "advance" : false, "currency" : { "id" : "usd", "name" : "USD", ... "organization" : { ... }, ... }, "description" : "Fixed share plan", "displayName" : "Fixed share plan", "earlyTerminationFee" : 10, "id" : "location_fixed_share_plan", "monetizationPackage" : { "description" : "Location", "displayName" : "Location", "id" : "location", "name" : "Location", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "description" : "Location", "displayName" : "Location", "id" : "location", "name" : "location", "organization" : { ... }, "status" : "CREATED" } ], "status" : "CREATED" }, "name" : "Fixed share plan", "organization" : { ... }, "paymentDueDays" : "30", "prorate" : false, "published" : true, "ratePlanDetails" : [ { "aggregateFreemiumCounters" : true, "aggregateStandardCounters" : true, "currency" : { "id" : "usd", "name" : "USD", ... "organization" : { ... }, ... }, "duration" : 1, "durationType" : "MONTH", "id" : "c1720153-c60f-4f7f-b4e5-cdc7bc7bec5b", "meteringType" : "UNIT", "organization" : { ... }, "paymentDueDays" : "30", "ratePlanRates" : [ { "id" : "01c4d544-d907-423b-964e-4e2aed2816a3", "revshare" : 80.8555, "startUnit" : 0, "type" : "REVSHARE" } ], "ratingParameter" : "VOLUME", "revenueType" : "NET", "type" : "REVSHARE" } ], "recurringStartUnit" : 1, "recurringType" : "CALENDAR", "setUpFee" : 10, "startDate" : "2013-09-15 00:00:00", "type" : "STANDARD" }
Specifying revenue share plan details for a flexible sharing model
In a flexible sharing model, you specify rate plan details that include one or more rate plan rates. Each rate plan rate covers a range of transaction revenue (each range is called a "revenue band"). You assign a revenue share percentage for each revenue band.
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).VOLUMEis the default. - A metering type (
VOLUME) that indicates that the revenue share is not based on the volume of transactions (that is, it’s not fixed, as is the case for the fixed sharing model). - The revenue type (
GROSSorNET). This indicates whether the revenue share is based on the gross or net price of a transaction. - 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 revenue is aggregated (this is also termed an "aggregation basis"). Transactions are aggregated over the aggregation basis (for example, 1 month) to calculate the total revenue and the applicable revenue band. The revenue share percentage applied to each transaction depends on its revenue band.
- Aggregation counters that are used to determine the applicable revenue band.
See Configuration properties for rate plan details for a complete list of rate plan detail properties.
For each rate plan rate, you specify:
- The type of the rate plan rate for the revenue band (
REVSHARE). - The percentage used to calculate the revenue share for the revenue band. For example, if you specify 80.5555, the revenue share for the revenue band is 80.5555%, that is, as an API provider, you pay the developer 80.5555% of the price charged for each transaction in that revenue band.
- The starting and ending unit of the revenue band. The starting unit specifies the lower
limit of a revenue band, and the ending unit specifies the upper limit of the revenue band. For
example, if you specify a starting unit of 0 and an ending unit of 1000, the revenue band
covers transaction revenue greater than 0 and up to 1000 in the specified currency. If the
currency is U.S. dollars, the aggregation basis is 1 month, and the percentage for the revenue
band is 80.5555%, then for transactions that generate up to $1000 in revenue in a month, the
revenue share is 80.5555% of the transaction price.
If you don’t specify an ending unit for final revenue band, the share percentage for that band is applied to all transactions after the aggregate revenue has gone above the starting unit for that band. For example if the starting unit for the last band is 1000 (assume U.S. dollars), and you do not specify an ending unit for that band, the revenue percentage for the band is applied to all transactions above $1000 of revenue during the aggregate period.
See Configuration properties for rate plans for a complete list of rate plan properties.
For example, the following creates a revenue share plan with a flexible sharing model. It specifies two revenue bands. The first band covers transaction revenue greater than to up to 1000 U.S. dollars. The second band covers transaction revenue over 1000 U.S. dollars. The revenue share percentage is 80.5555% for the first revenue band, and 90.5% for the second revenue band. The revenue share is based on the net price of a transaction. The aggregation basis is 1 month. The contract period is effective September 15, 2013, and payment is due in 30 days. (The revenue share-related details are highlighted.)
$ curl -H "Content-Type:application/json" -X POST -d \
'{
"name": "Flexible share plan",
"developer":null,
"developerCategory":null,
"advance": "true",
"currency": {
"id": "usd"
},
"description": "Flexible share plan",
"displayName": "Flexible share plan",
"frequencyDuration": "30",
"frequencyDurationType": "DAY",
"earlyTerminationFee": "10",
"monetizationPackage": {
"id": "location"
},
"organization": {
"id": "{org_name}"
},
"paymentDueDays": "30",
"prorate": "false",
"published": "true",
"ratePlanDetails": [
{
"currency": {
"id": "usd"
},
"duration": "1",
"durationType": "MONTH",
"meteringType": "VOLUME",
"organization": {
"id": "{org_name}"
},
"paymentDueDays": "30",
"ratePlanRates" : [ {
"endUnit" : 1000,
"revshare" : 80.5555,
"startUnit" : 0,
"type" : "REVSHARE"
}, {
"revshare" : 90.5,
"startUnit" : 1000,
"type" : "REVSHARE"
} ],
"ratingParameter" : "VOLUME",
"revenueType" : "NET",
"type" : "REVSHARE"
} ],
"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 response should look like this this (only part of the response is shown):
{ "advance" : true, "currency" : { "id" : "usd", "name" : "USD", "organization" : { ... }, ... }, "description" : "Flexible share plan", "displayName" : "Flexible share plan", "earlyTerminationFee" : 10, "frequencyDuration" : 30, "frequencyDurationType" : "DAY", "id" : "location_flexible_share_plan", "monetizationPackage" : { "description" : "Location", "displayName" : "Location", "id" : "location", "name" : "Location", "organization" : { ... }, "product" : [ { "customAtt1Name" : "user", "description" : "Location", "displayName" : "Location", "id" : "location", "name" : "location", "organization" : { ... }, "status" : "CREATED" } ], "status" : "CREATED" }, "name" : "Flexible share plan", "organization" : { ... }, "paymentDueDays" : "30", "prorate" : false, "published" : false, "ratePlanDetails" : [ { "aggregateFreemiumCounters" : true, "aggregateStandardCounters" : true, "currency" : { "id" : "usd", "name" : "USD", … "organization" : { ... }, ... }, "duration" : 1, "durationType" : "MONTH", "id" : "ba3353e3-14f4-4bc5-a9f1-c723fd34131c", "meteringType" : "VOLUME", "organization" : { ... }, "paymentDueDays" : "30", "ratePlanRates" : [ { "endUnit" : 1000, "id" : "5f13a51e-2250-4383-9aad-35e9a008ab40", "revshare" : 80.5555, "startUnit" : 0, "type" : "REVSHARE" }, { "id" : "d4196250-4ecc-480e-a7ed-dfab8e1c92ed", "revshare" : 90.5, "startUnit" : 1000, "type" : "REVSHARE" } ], "ratingParameter" : "VOLUME", "revenueType" : "NET", "type" : "REVSHARE" } ], "recurringFee" : 10, "recurringStartUnit" : 1, "recurringType" : "CALENDAR", "setUpFee" : 10, "startDate" : "2013-09-15 00:00:00", "type" : "STANDARD" }