Configure revenue share plan

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.

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