Was this helpful?

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).

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.

Toolbox

You can specify revenue share plan details using the management UI or monetization API. If you use the UI, you specify the details in the Generic Revenue Share window.

If you use the API, you specify revenue share 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 revenue share plan details using the UI

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

    This opens the Generic Revenue Share window.

  2. 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.

    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 fixed 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.

    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.

  3. Click Apply and Close to save the revenue share details and return to the Standard Rate Plan window.

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). VOLUME is 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 (GROSS or NET). 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 Rate plan details configuration settings for a complete list of rate plan detail options.

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 Rate plan configuration settings for a complete list of rate plan options.

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

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). VOLUME is 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 (GROSS or NET). 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 Rate plan details configuration settings for a complete list of rate plan detail options.

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 Rate plan configuration settings for a complete list of rate plan options.

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

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"
}

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.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.