Send Docs Feedback

Enforce monetization limits using the Monetization Limits Check policy

Attach the Monetization Limits Check policy to API proxies to enforce monetization limits. Specifically, the policy is triggered under the following conditions:

  • Developer accessing monetized API is not registered or has not subscribed to the rate plan.
  • Developer has exceeded the transaction volume for the subscribed rate plan.
  • Developer pre-paid account balance or post-paid credit limit has been reached.

The Monetization Limits Check policy is designed to raise a fault and block an API call in situations like those listed above. The policy extends the Raise Fault policy (see Raise Fault policy), and you can customize the message returned. The applicable conditions are derived from business variables.

Attaching a Monetization Limits Check Policy using the UI

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

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, as described in Build a simple API proxy, if monetization is installed, the Monetization configuration section appears on the Security page in the wizard. Select the Enable Monetization Limits Check  checkbox to attach a Monetization Limits Check policy.

Monetization Limits Check policy

Note that on the Build page of the wizard, the security settings are summarized. Ensure that the Monetization flag is enabled, indicating that the Monetization Limits Check policy will be attached to the API proxy.

The Monetization Limits Check policy is added to the ProxyEndpoint request PreFlow, after the VerifyAPI Key or AccessTokenValidation policy, as show in the following figure.

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

  1. In the API Proxy Editor, click PreFlow for the default proxy endpoint.
  2. In the Request flow, click +Step.
  3. Select Monetization Limits Check in the Mediation category.

  4. Modify the fields in the Add Step dialog, as desired, and click Add.

The policy is attached to the request flow after any VerifyAPI Key or AccessTokenValidation policy, and 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. Customize the response message, as required.

<Set>
     <Payload contentType="text/xml">
        <error>
           <messages>
               <message>Developer has reached usage quota</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.

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. The following provides example XML; customize the response message, as required.

<?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>
        <UserId>request.queryparam.user</UserId>
    </Variables>
    <FaultResponse>
        <Set>
            <Payload contentType="text/xml">
                <error>
                    <messages>
                        <message>Developer has reached usage quota</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.

 

Help or comments?