Was this helpful?

Introduction

You can set monetization-related limits. For example, you can limit the number of transactions on an API product, set an upper limit on the amount of credit that can be issued to developers, or specify a lower limit on the balance that a developer must maintain for purchasing API products.

You can also set up automatic notifications so that a developer is alerted when a limit is approaching or is reached. For details, see Set up limit notifications.

Limits that you can set are called explicit or custom limits. Contrast these with implicit limits — these include developer prepaid balance limits and postpaid balance limits. However, you can add notifications to inform developers when they are reaching or have reached these implicit limits.

To enforce the limits you set, a Monetization Limits Check policy must be attached to the request flow in API proxies that access your APIs. See Attaching a Monetization Limits Check policy in the UI or Attaching a Monetization Limits Check policy using the API for more details). The policy should be attached after any VerifyAPIKey policy in the request. It’s important that you instruct API proxy developers to add the Monetization Limits Check policy.

What you can limit

You have a lot of flexibility in setting custom limits. For example, you can set limits on transaction volume, or on the amount of money spent. You can set limits for all or specific users, developers, applications, products, and packages. You can even set limits for a specific time duration.

You can base limits on:

  • Transaction volume. The limit is based on the total volume of "rated" transactions. The success criteria for a rated transaction is defined in the transaction recording policy.
  • Spend limit. The limit is based on the total gross or net price of all transactions (for revenue sharing plans), plus the revenue share portion of revenue share and rate card plans, plus the total fees of all the transactions (for rate card plans, the rate card portion of revenue share and rate card plans, and set-up/recurring fees generated by all plans).
  • Fee Exposure. The limit is based on fees and not on the revenue share elements of any underlying plans.

You can apply the limits to:

  • Users (but only if you have a user attribute set up in your transaction recording policy). You can set limits for all, any, or specific users.
  • Applications. You can set limits for all, any, or specific applications created by your developers.
  • Developers. You can set limits for all, any, or specific developers.
  • API Products. You can set limits for all, any, or specific API products that you created.
  • API packages. You can set limits for all, any, or specific API packages that you created (that is, you added the API packages to the package catalog).
  • Developer billing types. You can set limits for prepaid developers, postpaid developers, or developers of all billing types.

"Any" means that the limit applies to any one user, application, developers, API product, or API package. For example, if you set a limit of 1000 transactions for “Any” developer, no one developer can exceed the limit of 1000 transactions.

"All" means that the limit applies to the sum of all users, or all developers, or all developer categories, and so on. For example, if you set a limit of 1000 transactions for "All" developers, then 1000 transactions is the limit for all developers combined — if one developer makes 500 calls and another developer makes 500 calls, the limit of 1000 is reached.

You can set the time period for a limit to:

  • 1 day
  • 1 week
  • 1 month
  • 1 year

In addition, you can set limits that halt execution. These are limits where you want to restrict a developer from sending API calls after the limit is reached.

All "halt execution" limits that are set for "any" or a "specific" developer (that is, not for "all"), are displayed in the developer portal catalog (in the API package details).

Toolbox

You can set limits using the management UI or monetization API. If you use the UI, you set limits on the Limits page.

If you use the API, you set limits by issuing a POST request to the /organizations/{org_name}/limits resource.

After you set limits, you can perform management operations on them such as update or delete. Management operations on limits are performed by issuing calls to the /organizations/{org_name}/limits/{limit_id}} resource.

Setting limits using the UI

To set a custom limit:

  1. On the Admin tab, select Limits.

    This opens the Limits page.

    The Limits page displays a summary of custom and implicit limits.

  2. Click + Limit on the Limits page. This opens the Add Limit page.

  3. Enter the following information in the Add Limit window:
    Field Description
    Name

    The name of the limit.

    Limit Conditions
    User

    This applies only if you set a custom attribute for a user in the transaction recording policy.

    User can be any unique identifier on which you want to place a limit, for example, an end user of an application, a mobile subscriber, or an agency reference. Select "All" to apply the limit to all users, select "Any" to apply the limit to any user, or select "Specific" to apply the limit to a specific user. If you select the "Specific" option, you need enter the value for the user as it would appear in the transaction record. For example, if the user is a mobile subscriber, enter the identifier as it would appear in the record, that is, the user’s phone number or anonymous customer reference (ACR).

    Application

    The application to which the limit applies. Select a specific application to apply the limit to a specific application belonging to a developer or partner, select "All" to apply the limit to all applications, or select "Any" to apply the limit to any application.

    Developer

    The developer to which the limit applies. Select a specific developer to apply the limit to a specific developer or partner, select "All" to apply the limit to all developers, or select "Any" to apply the limit to any developer.

    Product

    The API product to which the limit applies. Select a specific API product to apply the limit to a specific product, select "All" to apply the limit to all API products, or select "Any" to apply the limit to any API product.

    Sub Organization

     

    This limit condition appears only if your organization is a group organization and subsidiaries are specified in your organization profile.

    The sub-organization to which the limit applies. Select a specific sub-organization to apply the limit to that sub-organization, select "All" to apply the limit to all sub-organizations of the parent organization, or select "Any" to apply the limit to any sub-organization of the parent organization.

    Monetization Package

    The API package to which the limit applies. Select a specific API package to apply the limit to a specific API package, select “All” to apply the limit to all API packages, or select “Any” to apply the limit to any API package.

     

    If you set a limit for a package (All, Any, or specific a specific package) and you check the Halt Execution checkbox, execution is halted when the developer reaches that limit — even if are other limits belonging to the same package that have not been reached, such as an application or user limit.

    Developer Billing Type

    The developer billing type to which the limit applies. Select "Prepaid" to apply the limit to prepaid developers only, "postpaid" to apply the limit to postpaid developers only, or "All" to apply the limit to all developer billing types.

    Parameters
    Limit Based One

    The basis of the limit. Select one of the following:

    • Transaction Volume. The limit is based on the volume of transactions.
    • Transaction Value: Spend Limit. The limit is based on the total amount spent. For rate plans based on a rate card revenue model, the total spent is equal to the total amount of fees charged. For rate plans based on the revenue sharing revenue model, the total spent is equal to the total gross price or total net price (depending on whether the rate plan is on gross or net price). For rate cards based on revenue share and rate card revenue models, the total spent is equal to the total gross/net price plus the total amount of fees.
    • Transaction Value: Fee Exposure. The limit is based on the total fees charged. If there are transactions for plans based on revenue sharing or revenue sharing and rate card models, the revenue share element is not taken into account.
    Amount

    The limit amount. For limits based on transaction volume, enter a whole number. For limits based on transaction value enter a decimal number (with up to 2 decimal places).

    Currency

    This parameter appears only if your Limit Based on selection is Transaction Value: Spend Limit or Transaction Value: Fee Exposure.

    The currency that applies to the limit. If the limit is specified for an organization, or if your organization is a group organization with subsidiaries specified in the organization profile, and you select "All" or "Any" for a sub-organization, a drop-down menu displays all currencies supported by the organization and its sub-organizations. If the limit is specified for a specific sub-organization, a drop-down menu displays the currencies supported by that sub-organization. Select a currency from the drop-down menu.

    Start Date

    Optional. The start date for the limit. The field is preset with the default start date of today. To change the start date, select a date from the pop-up calendar.

    End Date

    Optional. The end date for the limit. Select a date from the pop-up calendar. You do not have to specify an end date to end a limit. The limit will expire if you display the limit details and click Expire Limit (see Expiring a limit for further details).

    Time Period

    Mandatory. The time period for the limit. Select a time period from the drop-down menu. Choose day, week, month, or year (the week, month and year selections are based on calendar periods).

    Halt Execution

    Indicates whether or not execution halts when the limit is reached (that is, future API calls are blocked). Check the checkbox to halt execution. If you do not check the checkbox, execution continues even if the limit is reached.

    You can set limits without a halt in execution -- do this if you want to notify yourself when a particular threshold is reached. For example, if any developer generates a certain amount of revenue in a certain time period using any of you API packages, or a specific API package, you can set up a limit to notify yourself of the event.

  4. Set up limit notifications (optional).
  5. Click Save to save the limit (and publish or delete it at a later date), Save and Publish (to publish the limit immediately), or Cancel (to discard the limit).

    After the limit is saved, it is added to the list of limits on the Limits page (as a custom limit).

    It takes approximately 10 minutes for the limit to become active.

Viewing a limit using the UI

To view a limit, click the limit name in the list on the Limits page. For example:

This displays the limit specification. In this case, the limit is set for 100 transactions per month involving the Location product. The limit is applies across all applications, products, and packages, for any user. This means that any unique user can never have more than 100 transactions per month across all packages, developers and applications.

Deleting a limit using the UI

You can delete a limit if it hasn't been published. After a limit is published, you can expire it but not delete it. In addition, you can only delete custom limits (not implicit limits).

To delete a custom limit:

  1. Click the custom limit name in the list on the Limits page.

    This displays the limit specification.

  2. Click Delete.

    You are then prompted to confirm or cancel the delete request.

  3. Click Delete in the prompt to delete the limit (or Cancel to cancel). The limit is removed from the Limits page, and is no longer in effect.

Expiring a limit using the UI

You can expire custom limits (however, you cannot expire implicit limits).

To expire a limit:

  1. Click the custom limit name in the list on the Limits page.

    This displays the limit specification.

  2. Click Expire Limit.

    You are then prompted to confirm or cancel the expire request.

  3. Click Expire in the prompt to expire the limit (or Cancel to cancel it). The limit is removed from the Limits page, and is no longer in effect.

A limits example

Suppose you created three API Products: A, B, and C. You want to give developers access to all three products, but you want to restrict their usage based the on their transaction volume and the total monthly fee they pay. To do that, you would set up different API Packages, each containing all three of your products. You would then associate a different fee plan with each package. You would also set a limit (based on transaction volume) for each of these packages. The limit can be based on daily and/or weekly and/or monthly time periods. For each limit set User = All, Application = All, Developer = Any, Package = Specific, Product = All, Developer Billing Type = All. Also check the Halt Execution checkbox.

Suppose the three API packages you set up are names Base, Premium, Gold. Base has a monthly fee plan of $100 recurring, Premium $150 recurring, and Gold $200 recurring. Base offers up to 100 transactions per day and 10000 per month, Premium 150 per day and 15000 per month, and Gold 200 per day and 20000 per month. Here’s what the three packages would look like in the package catalog.

Here is a view of the daily limit specification for the Base package:

Here is a view of the monthly limit specification for the Base package:

For the Premium package, you would set up a daily limit based on transaction volume with an amount set at 150, and a monthly daily limit based on transaction volume with an amount set at 15000.

For the Gold package, you would set up a daily limit based on transaction volume with an amount set at 200, and a monthly daily limit based on transaction volume with an amount set at 20000.

Attaching a Monetization Limits Check Policy using the UI

To enforce the limits you set, a Monetization Limits Check policy must be attached to the request flow in API proxies that access your APIs. The policy should be attached after any VerifyAPIKey policy in the request.

The Monetization Limits Check policy is designed to block an API call if a limit has been reached. The policy checks limits that have been set and raises a fault if a configured limit value has been reached or exceeded. The policy extends the Raise Fault policy (see Exception handling with RaiseFault), but the applicable conditions are derived from business variables.

You can attach a Monetization Limits Check policy when you create an API proxy or after an API proxy is created.

When you create an API proxy, you’re presented with a New API proxy page, as described in Build a simple API proxy. If monetization is installed, a Monetization checkbox is added to the Add Features section of the New API proxy page. Check the checkbox.

This adds the Monetization Limits Check policy to the ProxyEndpoint request PreFlow.

To add the Monetization Limits Check policy to an API proxy that has already been created:

  1. In the API Proxy Editor, click New Policy.
  2. Select Monetization Limits Check in the Mediation category.

  3. Modify the selections in the New Policy dialog to configure and attach the policy. The policy should be attached to the request flow after any VerifyAPI Key policy.

    If you accept the default selections, as shown below, the policy will be enforced on request messages from client apps to the ProxyEndpoint PreFlow.

By default, the XML for the policy sets the ContinueOnError field to false.

<MonetizationLimitsCheck enabled="true" continueOnError="false" async="false" name="Monetization-Limits-Check">

This means that the pipeline should not continue processing the message if the policy fails. In this case, a fault is raised if a limit is reached, with the fault response as set in the policy. By default, a 403 "Forbidden" message is returned.

<Set>
     <Payload contentType="text/xml">
        <error>
           <messages>
               <message>Exceeded developer limit configuration - {monetizationLimits.limitsMessageList} </message>
               <message>Is Developer Suspended - {monetizationLimits.isDeveloperSuspended} </message>
            </messages>
         </error>
     </Payload>
     <StatusCode>403</StatusCode>
     <ReasonPhrase>Forbidden</ReasonPhrase>
</Set>

If you set ContinueOnError to true, a fault will not be raised. In this case, the flow variables, mint.limitsViolated, mint.isDeveloperSuspended, and mint.limitsPolicyError are then automatically set. These variables can be used to perform further exception handling if required.

Setting limits using the API

To create a custom limit, issue a POST request to /organizations/{org_name}/limits. In making the request, you have a variety of options that give you flexibility in setting a custom limit. Some of the things you can specify are:

  • The basis of the limit. For example, you can specify a limit based on transaction volume, the amount spent, or on fees.
  • The limit amount, such as 1000 transactions or $1000.
  • To who or what the limit is applied. This can include any, all or specific users, developers, developer categories, applications, API products, and API packages, as well as all or specific developer billing types (such as prepaid developers).

    "Any" means that the limit applies to any one user, developer, developer category, application, API product, or API package. For example, if you set a limit of 1000 transactions for "Any" developer, no one developer can exceed the limit of 1000 transactions.

    "All" means that the limit is applies to the sum of all users, or all developers, or all developer categories, and so on. For example, if you set a limit of 1000 transactions for “All” developers, then 1000 transactions is the limit for all developers combined — if one developer makes 500 calls and another developer makes 500 calls, the limit of 1000 is reached.

  • The organization or sub-organization for which the limit applies.
  • The time unit for the limit, for example , day (such as 1000 transactions per day).
  • Whether or not to halt execution when the limit is reached.

See Limit configuration settings for a complete list of limit configuration options.

For example, the following request sets a limit of 20 transactions per user per day for a specific API product. Execution will be halted when the limit is reached. Notice that the requests sets the limit for any user and all developers, developer categories, API packages, and developer billing types.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
     "name": "Transaction limit per user per day",
     "organization": {
        "id": "{org_name}
     "userID": "ANY",
     "developer": "ALL",
     "developerCategory": "ALL",
     "monetizationPackage": "ALL",
     "product": "payment",
     "developerBillingType": "ALL",
     "application": "ALL",
     "quotaLimit": 20,
     "quotaType": "Transactions",
     "quotaPeriodType": "CALENDAR",
     "durationType": "DAY",
     "published": "true",
     "haltExecution": "true",     
     "startDate": "2013-09-15 00:00:00"
}' \
"https:// api.enterprise.apigee.com/v1/mint/organizations/{org_name}/limits" \
-u myname:mypass

The response should look like this (only part of the response is shown):

{
  "application" : "ALL",
  "currency" : "NULL",
  "developer" : "ALL",
  "developerBillingType" : "ALL",
  "developerCategory" : "ALL",
  "durationType" : "DAY",
  "haltExecution" : true,
  "id" : "e2756f13-724b-4924-ab04-6aa22c60efea",
  "limitKey" : "limit## myorg##ALL##ALL##myorg@@@payment##ALL##ALL##ALL##ALL##ALL##ALL##Transactions##NULL##DAY",
  "monetizationPackage" : "ALL",
  "name" : "Transaction limit per user per day",
  "organization" : {   
    "name" : "{org_name}", 
    ...
  },
  "product" : "payment",
  "published" : false,
  "quotaLimit" : 20,
  "quotaPeriodType" : "CALENDAR",
  "quotaType" : "Transactions",
  "startDate" : "2013-09-15 00:00:00",
  "subOrganization" : "ALL",
  "userId" : "ALL"
}

Retrieving limits using the API

You can retrieve a specific limit or all limits for an organization. To retrieve a specific limit issue a GET request to /organizations/{org_name}/limit/{limit_id}, where {limit_id} is the identification of the limit (the ID is returned in the response when you create the limit). For example:

$ curl -H "Accept:application/json" -X GET \
"https api.enterprise.apigee.com /v1/mint/organizations/{org_name}/limits/e2756f13-724b-4924-ab04-6aa22c60efea" \
-u myname:mypass

To retrieve all the limits for the organization, issue a GET request to /organizations/{org_id}/limits. For example:

$ curl -H "Accept:application/json" -X GET \
"https api.enterprise.apigee.com /v1/mint/organizations/{org_name}/limits" \
-u myname:mypass

Updating a limit using the API

To update a limit, issue a PUT request to /organizations/{org_name}limits/{limit_id}, where {limit_id} is the identification of the limit to be updated. When you make the update, you need to specify in the request body the updated settings and the ID of the limit.

For example, the following request updates a limit to 30 transactions per user per day for a specific API product (from a limit of 20 transactions per user per day).

$ curl -H "Content-Type: application/json" -X PUT -d \
'{
     "id": "e2756f13-724b-4924-ab04-6aa22c60efea",
     "name": "Transaction limit per user per day (update)",
     "organization": {
            "id": "{org_name}"
      },
     "userID": "ANY",
     "developer": "ALL",
     "developerCategory": "ALL",
     "monetizationPackage": "ALL",
     "product": "payment",
     "developerBillingType": "ALL",
     "application": "ALL",
     "quotaLimit": 30,
     "quotaType": "Transactions",
     "quotaPeriodType": "CALENDAR",
     "durationType": "DAY",
     "published": "false",
     "haltExecution": "true",     
     "startDate": "2013-09-15 00:00:00"
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name/limits/e2756f13-724b-4924-ab04-6aa22c60efea" \
-u myname:mypass

Deleting a limit using the API

To delete a limit, issue a DELETE request to /organizations/{org_name}/limits/{limit_id}, where {limit_id} is the identification of the limit. For example:

$ curl -H "Accept:application/json" -X DELETE \
"https api.enterprise.apigee.com /v1/mint/organizations/{org_name}/limits/e2756f13-724b-4924-ab04-6aa22c60efea" \
-u myname:mypass

Attaching a Monetization Limits Check Policy using the API

You can attach the Monetization Limits Check policy to an API proxy programmatically, as described in Policy attachment and enforcement. Typically, policies are created as XML files and stored under the /apiproxy/policies directory. Here is the XML for the policy when you attach the policy using the UI.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MonetizationLimitsCheck enabled="true" continueOnError="false" async="false" name="Monetization-Limits-Check">
    <DisplayName>Monetization Limits Check</DisplayName>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <FaultRules/>
    <Properties/>
    <Variables>
        <ClientId>request.queryparam.apikey</ClientId>
        <Product>apiproduct.name</Product>
        <Currency>request.queryparam.currency</Currency>
        <SubOrg>request.queryparam.subOrg</SubOrg>
        <UserId>request.queryparam.user</UserId>
    </Variables>
    <FaultResponse>
        <Set>
            <Payload contentType="text/xml">
                <error>
                    <messages>
                        <message>Exceeded developer limit configuration - {monetizationLimits.limitsMessageList} </message>
                        <message>Is Developer Suspended - {monetizationLimits.isDeveloperSuspended} </message>
                    </messages>
                </error>
            </Payload>
            <StatusCode>403</StatusCode>
            <ReasonPhrase>Forbidden</ReasonPhrase>
        </Set>
    </FaultResponse>
</MonetizationLimitsCheck> 

Notice that the ContinueOnError field is set to false. This means that the pipeline should not continue processing the message if the policy fails. In this case, a fault is raised if a limit is reached, with the fault response as set in the policy. By default, a 403 'Forbidden" message is returned.

If you set ContinueOnError to true, a fault will not be raised. In this case, the flow variables, mint.limitsViolated, mint.isDeveloperSuspended, and mint.limitsPolicyError are then automatically set. These variables can be used to perform further exception handling if required.

Limit configuration settings

The following limit configuration options are exposed to the API:

Name Description Default Required?
name

The name of the limit.

N/A Yes
organization

The organization for which the limit applies.

N/A No
subOrganization

The sub-organization for which the limit applies.

N/A No
developerCategory

The developer category for which the limit applies. The value can be one of the following:

  • A specific developer category. This applies the limit to a specific developer category.
  • ALL. This applies the limit to all developer categories.
  • ANY. This applies the limit to any developer category.

 

N/A No
developer

The developer for which the limit applies. The value can be one of the following:

  • A specific developer. This applies the limit to a specific developer.
  • ALL. This applies the limit to all developers.
  • ANY. This applies the limit to any developer.

 

N/A No
monetizationPackage

The API package for which the limit applies. The value can be one of the following:

  • A specific API package. This applies the limit to a specific API package.
  • ALL. This applies the limit to all API packages.
  • ANY. This applies the limit to any API package.

 

N/A No
product

The API product for which the limit applies. The value can be one of the following:

  • A specific API product. This applies the limit to a specific API product.
  • ALL. This applies the limit to all API products.
  • ANY. This applies the limit to any API product.

 

N/A No
application

The application for which the limit applies. The value can be one of the following:

  • A specific application. This applies the limit to a specific application.
  • ALL. This applies the limit to all applications.
  • ANY. This applies the limit to any application.

 

N/A No
userId

The user for whom the limit applies. The value can be one of the following:

  • A specific user ID. This applies the limit to a specific user.
  • ALL. This applies the limit to all users.
  • ANY. This applies the limit to any user.

 

N/A No
developerBillingType

The developer billing type for which the limit applies. The value can be one of the following:

  • A specific developer billing type . This applies the limit to a specific developer billing type (such as prepaid).
  • ALL. This applies the limit to all developer billing types.

 

N/A No
quotaLimit

The limit amount. For limits based on transaction volume, enter a whole number. For limits based on transaction value enter a decimal number (with up to 2 decimal places).

N/A Yes
currency

The currency used for the limit, such as usd for Unites States dollars.

N/A No
quotaType

The basis of the limit. The value can be one of the following:

  • Transactions. The limit is based on the volume of transactions.
  • SpendLimit. The limit is based on the total amount spent. For rate plans based on a rate card revenue model, the total spent is equal to the total amount of fees charged. For rate plans based on the revenue sharing revenue model, the total spent is equal to the total gross price or total net price (depending on whether the rate plan is on gross or net price). For rate cards based on revenue share and rate card revenue models, the total spent is equal to the total gross/net price plus the total amount of fees.
  • FeeExposure. The limit is based on the total fees charged. If there are transactions for plans based on revenue sharing or revenue sharing and rate card models, the revenue share element is not taken into account.

 

N/A Yes
quotaPeriodType

The basis of the time period used for the limit. The value can be one of the following:

  • CALENDAR. The limit period is based on the first to last day of the month or week (depending on the durationType).
  • USAGE_START. The limit period is from the date when usage starts until the corresponding day of the next month or week (depending on the durationType). For example, if usage starts on August 15 and the durationType is MONTH, the limit period is from August 15 to September 15.
  • ROLLING. The quota period is carried forward to the next week or month on a repeating basis (depending on the durationType). For example, if the limit period is for a month, the limit is repeated each successive month.

 

CALENDAR Yes
durationType

The time period unit for the limit. . The value can be one of the following:

  • DAY
  • WEEK
  • MONTH
  • YEAR

 

N/A No
limitKey

A system-generated key for the limit.

N/A No
published

Indicates whether or not the limit should be published for viewing by developers. The value can be one of the following:

  • true. Publish the limit.
  • false. Do not publish the limit.

 

N/A No
haltExecution

Indicates whether execution is halted if the limit is reached. The value can be one of the following:

  • true. Halt execution if the limit is reached.
  • false. Do not halt execution if the limit is reached.

 

N/A No
startDate

The starting date for applying the limit.

N/A No
endDate

The ending date for applying the limit.

N/A No

Get help

For help, see Apigee Customer Support.

Next steps

 

Learn how to set up automatic notifications for limits in Set up limit notifications.

 

コメントを追加

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.