Set a customer’s auto top-up
Set a customer’s auto top-up
Buys credits for the customer when a pool’s available balance falls to the threshold, up to target_balance, charging the payment method the customer saved at checkout. It replaces any auto top-up the customer has. The customer’s plan must allow it (top_up.auto.allowed), the customer must have a saved payment method (otherwise invalid_state), and a monthly_limit above the plan’s maximum_monthly_limit is parameter_invalid. The limit caps automatic purchases only, and a spend limit caps consumption. Setting a customer’s auto top-up is a runtime write that takes auto_top_up:write. An agent key may turn it on within the plan’s bounds or lower the limit, but not raise the limit in live. Credits it buys expire after the plan’s top_up.credits_expire_in, or after one year when the plan sets none, the same as any other top-up. Creating the rule, changing it and turning it off (status disabled) each write an audit event with the actor: auto_top_up.created, auto_top_up.updated or auto_top_up.turned_off.
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Path parameters
The customer ID (cus_...).
Request
Buy enough to bring the available balance back to this. The purchase respects the plan’s top-up minimum and maximum.
The pool to keep topped up. Defaults to the plan’s top_up.pool.
false buys nothing and keeps the threshold, so balance.low still goes out when the balance falls to it.
Response
The customer’s auto top-up.
active tops up. disabled stopped after three failures in a row, or because you turned it off. Set it again to re-enable.
What automatic purchases have cost since the start of the calendar month (UTC).