Skip Navigation
Show nav
Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
    • .NET
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Compute (Dynos)
      • Dyno Management
      • Dyno Concepts
      • Dyno Behavior
      • Dyno Reference
      • Dyno Troubleshooting
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Developer Tools
    • Command Line
    • Heroku VS Code Extension
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery & Integration (Heroku Flow)
    • Continuous Integration
  • Language Support
    • Node.js
      • Working with Node.js
      • Node.js Behavior in Heroku
      • Troubleshooting Node.js Apps
    • Ruby
      • Rails Support
      • Working with Bundler
      • Working with Ruby
      • Ruby Behavior in Heroku
      • Troubleshooting Ruby Apps
    • Python
      • Working with Python
      • Background Jobs in Python
      • Python Behavior in Heroku
      • Working with Django
    • Java
      • Java Behavior in Heroku
      • Working with Java
      • Working with Maven
      • Working with Spring Boot
      • Troubleshooting Java Apps
    • PHP
      • PHP Behavior in Heroku
      • Working with PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
    • .NET
      • Working with .NET
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
      • Migrating to Heroku Postgres
    • Heroku Key-Value Store
    • Apache Kafka on Heroku
    • Other Data Stores
  • AI
    • Working with AI
    • Heroku Inference
      • Inference API
      • Quick Start Guides
      • AI Models
      • Inference Essentials
    • Vector Database
    • Model Context Protocol
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
      • Single Sign-on (SSO)
    • Private Spaces
      • Infrastructure Networking
    • Compliance
  • Heroku Enterprise
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Extending Heroku
  • Building Add-ons
  • Add-on Guidelines & Requirements
  • Customer Plan Usage Control Guidelines for Add-on Partners

Customer Plan Usage Control Guidelines for Add-on Partners

English — 日本語に切り替える

Last updated February 06, 2024

Table of Contents

  • Set threshold limits for your plans
  • Communication
  • Mitigations
  • Get in touch

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

The 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, 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.

Keep reading

  • Add-on Guidelines & Requirements

Feedback

Log in to submit feedback.

The Add-on Ownership Model and User Authentication Guidelines for Add-on Partners Getting Support as an Add-on Partner

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure
  • .NET

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing
  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Github
  • LinkedIn
  • © 2025 Salesforce, Inc. All rights reserved. Various trademarks held by their respective owners. Salesforce Tower, 415 Mission Street, 3rd Floor, San Francisco, CA 94105, United States
  • heroku.com
  • Legal
  • Terms of Service
  • Privacy Information
  • Responsible Disclosure
  • Trust
  • Contact
  • Cookie Preferences
  • Your Privacy Choices