Auto-recharge

Auto-recharge charges your saved card a fixed amount whenever the organization’s balance drops below a threshold you choose. Turn it on if your runs must not stop at 402 insufficient_credits while nobody is watching the balance. This page covers the one route that configures it, the rules it validates, when a charge actually happens, and how to confirm it worked. You can set the same two numbers on the Billing page in the console, in the fields When below, $** and **Buy,$ .

Before you start

You need billing_write. Owners, admins and billing users hold it; members and viewers do not. See Credits and billing.
You need a saved card. GET /v1/billing reports it as has_payment_method. Paying through checkout saves the card, or you can add one in the billing portal (POST /v1/billing/portal) without buying anything. Without a card, auto-recharge can be enabled but never charges.

Turn it on

PUT /v1/billing/auto-recharge sets auto-recharge and returns the updated billing state, the same body as GET /v1/billing.

Field	Type	Required	Rule
`enabled`	boolean	always	`true` turns auto-recharge on, `false` turns it off
`threshold_micros`	integer	when `enabled` is `true`	The balance below which a charge is made. At most 1,000,000,000 ($1,000).
`amount_micros`	integer	when `enabled` is `true`	What each charge buys. 5,000,000 to 1,000,000,000 micros ( $5 to$ 1,000), in whole cents (a multiple of 10,000).

The body refuses any other field. Every amount is micro-USD: 1,000,000 micros is 1 US dollar.

curl -sS https://api.opentype.dev/v1/billing/auto-recharge \
  -X PUT \
  -H "Authorization: Bearer $OPENTYPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold_micros": 5000000, "amount_micros": 20000000}'

const res = await fetch("https://api.opentype.dev/v1/billing/auto-recharge", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.OPENTYPE_API_KEY}`,
    "Content-Type": "application/json",
  },
  // Below $5, buy $20.
  body: JSON.stringify({ enabled: true, threshold_micros: 5_000_000, amount_micros: 20_000_000 }),
});
if (!res.ok) throw new Error(`auto-recharge update failed: ${res.status} ${await res.text()}`);
const billing = await res.json();
if (!billing.has_payment_method) {
  console.warn("Auto-recharge is on but no card is saved: open the billing portal to add one.");
}

import os
import requests

res = requests.put(
    "https://api.opentype.dev/v1/billing/auto-recharge",
    headers={"Authorization": f"Bearer {os.environ['OPENTYPE_API_KEY']}"},
    # Below $5, buy $20.
    json={"enabled": True, "threshold_micros": 5_000_000, "amount_micros": 20_000_000},
    timeout=30,
)
res.raise_for_status()
billing = res.json()
if not billing["has_payment_method"]:
    print("Auto-recharge is on but no card is saved: open the billing portal to add one.")

{
  "organization_id": "org_example",
  "balance_micros": 24981000,
  "currency": "usd",
  "auto_recharge": {"enabled": true, "threshold_micros": 5000000, "amount_micros": 20000000},
  "has_payment_method": true,
  "transactions": [
    {"id": "txn_usage_20260924", "kind": "usage", "amount_micros": -19000,
     "description": "Usage on 2026-09-24", "created_at": "2026-09-24T00:00:00Z"}
  ]
}

Turn it off

Send enabled: false. The threshold and amount are optional then.

curl -sS https://api.opentype.dev/v1/billing/auto-recharge \
  -X PUT \
  -H "Authorization: Bearer $OPENTYPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

await fetch("https://api.opentype.dev/v1/billing/auto-recharge", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.OPENTYPE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ enabled: false }),
});

import os
import requests

requests.put(
    "https://api.opentype.dev/v1/billing/auto-recharge",
    headers={"Authorization": f"Bearer {os.environ['OPENTYPE_API_KEY']}"},
    json={"enabled": False},
    timeout=30,
).raise_for_status()

When a charge happens

Saving the setting does not charge anything. The check runs in the background at two moments:

after each run is admitted by POST /v1/runs, and
after each run is refused with 402 insufficient_credits.

At that moment a charge is made only if all of these hold:

Condition	Where to see it
Auto-recharge is enabled	`auto_recharge.enabled`
A card is saved	`has_payment_method`
The available balance is below `threshold_micros`	`balance_micros`, which already has the holds of runs in flight subtracted
No auto-recharge charge was made for the organization in the current clock hour	at most one charge per organization per clock hour

The charge is amount_micros on the saved card. The credit lands when the payment succeeds, as a purchase transaction with the description Auto-recharge. What follows from those rules:

Nothing happens without traffic. If no run is sent, no check runs, even when the balance is below the threshold. Buy credit through checkout if you need the balance up now.
The run that triggers a charge is not held for it. A run admitted while the balance is low goes ahead on the current balance. A run refused with 402 stays refused: the charge it queued helps the next attempt, once the payment has landed.
One charge per hour is the ceiling. If one hour’s spend is larger than amount_micros, the balance can still run out before the next hour. Size amount_micros above your busiest hour, or buy extra credit through checkout.
Changing the setting takes effect at the next check. The next admitted or refused run sees the new values.

Pick the numbers

Threshold: at least your spend over the time a charge takes to land, plus 20,000 micros so the next run can still start. Every run needs 20,000 micros of available credit to be admitted.
Amount: at least one busy hour of spend, because one charge per hour is the most you get. Read your spend per day from GET /v1/usage/daily to size it.

For example, a pipeline that settles about

2 an hour at its peak is covered by a

5 threshold and a $20 amount.

Confirm it works

Read GET /v1/billing and check auto_recharge.enabled is true, both numbers are what you sent, and has_payment_method is true.
After the balance has dropped below the threshold and a run has been sent, look for a new purchase row described Auto-recharge in transactions.
If none appears, check the saved card in the billing portal, and check that a charge was not already made in the same clock hour.

Errors

Status	Code	When	What to do
`400`	`invalid_amount`	`threshold_micros and amount_micros are required when enabled`	Send both numbers with `enabled: true`
`400`	`invalid_amount`	`threshold_micros must not exceed 1000000000`	Use a threshold of $1,000 or less
`400`	`invalid_amount`	`amount_micros must be between 5000000 and 1000000000` or `amount_micros must be a whole number of cents`	Use $5 to$ 1,000 in a multiple of 10,000 micros
`403`	`scope_denied`	The key lacks `billing_write`	Use a key created by an owner, admin or billing user with that scope
`503`	`billing_not_configured`	Billing is not switched on for this deployment	Retry later
`503`	`database_unavailable`	Storage is unreachable	Retry with backoff

Malformed JSON, an unknown field, a wrong type or a missing Content-Type gets a plain-text 400, 415 or 422 with no JSON envelope. Check the body against the field table above.

Credits and billing - the balance, checkout and the billing portal.
Handling insufficient credits - what your code does when a run gets 402.
Billing in the console - set the threshold and amount without code.
Usage reporting - measure your daily spend to size the amount.

Overview

Decision runs

Model Router

Reliable requests

Spend and billing

Go to production

Before you start

Turn it on

Turn it off

When a charge happens

Pick the numbers

Confirm it works

Errors

​Before you start

​Turn it on

​Turn it off

​When a charge happens

​Pick the numbers

​Confirm it works

​Errors

​Related

Before you start

Turn it on

Turn it off

When a charge happens

Pick the numbers

Confirm it works

Errors

Related