Customer Plan Usage Control Guidelines for Add-on Partners
Last updated 27 February 2019
Heroku charges add-on plans at a monthly fee, pro-rated to the second. This can be a challenge for some add-on partners, who provide services that may “burst” in usage and are not incurred evenly over time. In this article, we’ll present a set of principles and techniques to help manage this discrepancy, and to identify and block potentially abusive customers.
Keep in mind not all harmful usage is abuse - customers may just be unaware of the impacts of their actions. You may simply need to alert the customer about acceptable use of your add-on to mitigate negative impacts.
However, we recognize that abuse of your add-on for spam or fraudulent use is a serious concern. If you believe an add-on is being misused, please disable it and contact us.
Set threshold limits for your plans.
You’re most definitely doing this, but be sure to keep track of resource usage relative to your plan limits. Once you’re tracking resource usage, you can create a set of alarms that fire when a customer crosses certain usage thresholds.
An alarm might trip when a customer uses 50% of a plan’s monthly resources in the first week, for instance. When this alarm is tripped, contact the customer to let them know they may need to upgrade their current plan. You might calculate expected average daily resource usage metrics for each plan tier, and use those metrics to guide your threshold alarms.
You should probably implement a few thresholds at different levels and contact the customer when they are crossed. This will ensure any future corrective measures you take aren’t a surprise.
Our Syncing User Access article can help you get a complete list of users associated with an add-on installation.
Be sure to communicate with your customers through your SSO dashboard and (when appropriate) via email. Which communication method makes the most sense depends on how customers use your add-on. It is better to communicate about threshold limit problems early than to silently take action.
Consider creating a set of reports in your add-on SSO dashboard that allows customers to understand resource usage relative to plan limits.
Be sure to describe to customers the consequences of not upgrading in your communications. You might discard old messages, reject new transactions, etc.
The ability to provision, deprovision, upgrade, and downgrade plans is in the customer’s hands. This doesn’t mean you have no options at your disposal, though. Here are some possible mitigations:
Reject plan downgrades
You can reject plan downgrade requests (aka a “plan change” request for a lower tier plan). You might do this if a customer has used plan resources too quickly before requesting a downgrade, and this may be based on the thresholds you’ve previously created.
If you decide to reject a plan change, you should include a
message in the JSON response that describes why you’ve rejected the downgrade. Please see the Add-on Partner API reference for more information. Rejecting a plan change request may lead to a support ticket, so be explicit in the
message you return to help the customer and support staff debug.
Reject plan provisions
When a customer deprovisions an add-on, we immediately stop billing and send add-on partners a request to deprovision the resource. You cannot reject a deprovisioning event. You can reject a provisioning request, however.
If you find that customers are provisioning your add-on, using resources and then deprovisioning too quickly, you can reject subsequent provisioning requests with a
message in the JSON response describing why.
Asynchronous provisioning under the Add-on Partner API allows you to conditionally accept a provisioning request, make a decision, and then permanently accept or reject it at your leisure. The Platform API for Partners can help you get detailed info about environment the add-on is deployed to, including application, team, and collaborator metadata.
To make a decision about whether or not to accept a provisioning request, you might look at:
- How many times an application has provisioned and deprovisioned your add-on (and when)
- Previous usage from the application
- Activity related to your add-on from the app owner or collaborators
- Other metrics about the application that you track internally
- Metadata that you retrieve via the Platform API for Partners
When you’ve made your decision, you use the add-on action endpoints through the Platform API for Partners to accept or reject the provisioning request.
If you’re using synchronous provisioning, you can just issue a 422 error response with a relevant
message when failing a provisioning request. However, you will not be able to use most of the Platform API for Partners during a synchronous provisioning response. This is because the resource has not been fully committed to persistence until we receive a response from you. You have more options available to you under asynchronous provisioning.
Think through your plan tiers
You may want to modify your plan tiers to more readily capture common customer usage patterns, making it easier for customers to choose the correct plan. We can assist repricing plans, or (in rare cases) with the mass migration of customers from one plan to another.
Get in touch
Please get in touch if you’d like to discuss how to mitigate plan usage problems or suspected add-on abuse.