Skip to content

Set automatic top-up

Set or turn off automatic wallet top-ups from the saved card. Top-ups are limited to five per day and the monthly budget.

Parameters

#
amountstring
Automatic wallet top-up amount, in whole dollars from 5 to 1000.
monthly_limitstring
Monthly automatic top-up budget, in whole dollars: at least one top-up and at most $5,000. Defaults to the existing budget, or $500.
offboolean
Turn off automatic wallet top-ups.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
The saved automatic wallet top-up settings.
Show 2 attributesHide attributes
amount_centsinteger | nullAlways present
Amount added per automatic top-up, in cents. Null disables automatic top-ups.
monthly_limit_centsintegerAlways present
Monthly ceiling on automatic top-ups, in cents.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create).
  • A key limited to a command list cannot run this command.
  • A key limited to a command list must also allow billing top-up.
  • On: Top up from the saved card when the wallet has less than a day of use remaining. Required: amount. Optional: monthly_limit, organization.
  • Off: Disable automatic wallet top-ups and cancel any still queued. Required: off. Optional: organization.