Skip to main content
Auto top-up charges the organization’s saved card for a fixed dollar amount whenever the credit balance falls below a threshold you set. It is configured on the Billing page in the dashboard. Only organization admins can buy credits, save a card, or configure auto top-up. Organizations billed by invoice cannot turn it on.

​
Set up auto top-up

1

Buy credits first

The threshold cannot be higher than the current balance, because that would trigger a purchase immediately. If the balance is already low, buy credits from Buy Credits on the Billing page before configuring auto top-up.
2

Save a card

In the Payment Method panel, select Add Card (or Replace to change an existing card). Stripe stores the card for future purchases. Modulate does not store card details.
3

Set the threshold and purchase amount

In the Auto Top-Up panel, select Turn On, then enter:
  • When credits fall below: the credit balance that triggers a purchase.
  • Purchase amount (USD): the dollar amount charged on each purchase. Credits added shows how many credits that buys at the organization’s current rate.
4

Turn it on

Select Turn On Auto Top-Up. Turning it on authorizes a charge of the purchase amount to the saved card each time the balance falls below the threshold.
Modulate cannot set up auto top-up on an organization’s behalf, because Modulate does not hold the payment details.

​
Settings

Two checks apply when the settings are saved:
  • The purchase must clear the threshold. Each purchase must add at least 110% of the threshold in credits at the current rate. With a threshold of 500 credits, a purchase must add at least 550 credits. This check runs only at save time; it is not repeated when the organization’s credit rate changes later.
  • The threshold cannot exceed the balance. This applies when turning auto top-up on and when changing the threshold while it is on.

​
Timing

A purchase is not instant. Organizations are checked against their thresholds every 60 seconds, and the Stripe charge for an organization below its threshold can take a few more minutes to complete. Set the threshold high enough that the organization’s usage will not consume it within about 5 minutes. If the balance reaches zero before the purchase completes, requests are rejected with 429 Insufficient credits. (WebSocket close code 4029) until the credits arrive. See Authentication and rate limits. Auto top-up does not depend on API activity. A balance below the threshold triggers a purchase whether or not requests are being made.

​
The 6-hour limit

Auto top-up makes at most one purchase every 6 hours per organization. This limits spending if usage, or a misconfiguration, drains credits faster than expected.
  • Set the purchase amount high enough to cover at least 6 hours of usage. If the balance falls below the threshold again inside the window, no purchase is made until the window ends, and the purchase is then made at the next check.
  • Saving the settings while auto top-up is on restarts the 6-hour window.
  • A declined charge does not start the window.
The Auto Top-Up panel shows the time after which the next automatic purchase can happen.

​
Credit rate

Each purchase converts the dollar amount to credits at the organization’s credit rate at the time of purchase. Fractional credits are rounded up. A contract that changes the rate changes the credits each purchase adds. The purchase amount does not change.

​
Turn off auto top-up

Open the Auto Top-Up panel, select Manage, then Turn Off. Turning it off is never refused. A purchase that is already being charged can still complete after it is turned off. Auto top-up also turns itself off in these cases. The panel then shows Turned off with the reason: Modulate support can turn auto top-up off for an organization, but cannot turn it on.