Last updated February 06, 2024

Heroku charges add-on plans at a monthly fee, which is prorated to the second. This can be a challenge for some add-on partners, because the services they provide may “burst” in usage and are not incurred evenly over time. In this article, learn about a set of principles and techniques to help manage this discrepancy, and to identify and block potentially abusive customers.

Keep in mind that not all harmful usage is abuse - customers may just be unaware of the impacts of their actions. Alert the customer about acceptable use of your add-on to mitigate negative impact.

However, add-on abuse that involves 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

Be sure to keep track of resource usage relative to your plan limits. Once you are tracking resource usage, you can create a set of alarms that go off when a customer crosses certain usage thresholds.

For example, an alarm might trip when a customer uses 50% of a plan’s monthly resources in the first week. When this alarm is tripped, contact the customer to let them know they may need to upgrade their current plan. Calculate the expected average daily resource usage metrics for each plan tier, and use those metrics to guide your threshold alarms.

It is recommended to implement a few thresholds at different levels and to contact the customer when they are crossed. This will ensure that the customer does not get surprised when you make any future corrective measures.

Communication

Be sure to communicate with your customers through your SSO dashboard and, when appropriate, 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 communicate and describe the consequences of not upgrading to your customers. For example, describe how not upgrading can lead to discarding old messages, rejecting new transactions, and other unintended actions.

Mitigations

The ability to provision, deprovision, upgrade, and downgrade plans is in the customer’s hands. However, you still have some possible options for mitigation:

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, include a message in the JSON response that describes why you 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, Heroku immediately stops billing and sends add-on partners a request to deprovision the resource. You cannot reject a deprovisioning event. However, you can reject a provisioning request.

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 that describes the reason for the rejection.

Asynchronous Provisioning

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 discretion. 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, consider:

• 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, use the add-on action endpoints through the Platform API for Partners to accept or reject the provisioning request.

Synchronous Provisioning

If you’re using synchronous provisioning, you can issue a 422 error response with a relevant message when failing a provisioning request. However, you cannot 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 Heroku receives 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. Heroku 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 like to discuss how to mitigate plan usage problems or suspected add-on abuse.