---
title: "Arm auto top-up (buy item_id off-session when the balance falls below threshold_credits; it spends within the account's agent period limit) or turn it off; audited; counts toward 30 billing-settings changes per hour"
method: PUT
path: "/v1/account/billing/auto-topup"
---

# Arm auto top-up (buy item_id off-session when the balance falls below threshold_credits; it spends within the account's agent period limit) or turn it off; audited; counts toward 30 billing-settings changes per hour

`PUT /v1/account/billing/auto-topup`

## Request

- Base URL: `https://api.roveapi.com`
- URL: `https://api.roveapi.com/v1/account/billing/auto-topup`
- Auth: API key in cookie `rove_session`

## Request body

- object
  - `state` 'off' | 'armed', required
  - `threshold_credits` integer: Required to arm: buy when the balance falls below this many whole credits. Ignored when state is off.
  - `item_id` string: Required to arm: a current catalogue pack whose price is within the per-purchase limit. Ignored when state is off.

## Response `200`

Successful response (Cache-Control: no-store)

- object
  - `state` 'off' | 'armed' | 'in_flight' | 'paused', required: off until the owner arms it; in_flight while its purchase is being paid; paused until the owner arms it again (or its handoff is paid).
  - `threshold_credits` integer, nullable, required: Buys when the balance falls below this many whole credits; null until first configured.
  - `item_id` string, nullable, required: The catalogue pack it buys; null until first configured.
  - `blocked_until` string, date-time, nullable, required: Set when the account's agent period limit refused it: it waits until then (the period end).
  - `pause_reason` 'no_saved_method' | 'off_session_not_allowed' | 'purchasing_off' | 'item_retired' | 'exceeds_per_purchase_limit' | 'authentication_required' | 'card_declined' | 'stripe_request_unconfirmed', nullable, required
  - `in_flight_purchase_id` string, uuid, nullable, required: The purchase it follows: the one in flight, or the handoff a paused (authentication_required) one waits on; read it at /v1/account/billing/purchases/{id} for the payment link.
  - `saved_method` object, nullable, required: The saved card it charges, or null.
    - `brand` string, nullable, required
    - `last4` string, nullable, required
    - `exp_month` integer, nullable, required
    - `exp_year` integer, nullable, required

## Other responses

- `400`: RFC 7807 invalid-params
- `401`: RFC 7807 owner-session-required: sign in at owner_action_url
- `403`: RFC 7807 owner-origin-refused (mutations only)
- `404`: RFC 7807 pack-not-found: no catalogue pack has this id
- `409`: RFC 7807 auto-topup-precondition: reason no_saved_method, off_session_not_allowed, purchasing_off, item_retired or exceeds_per_purchase_limit (checked in this order)
- `429`: RFC 7807 billing-settings-rate-limited: 30 owner billing-settings changes per account per trailing hour; Retry-After and retry_after_seconds
- `503`: RFC 7807 billing-unavailable; Retry-After: 30, retry same_key

---

[API](https://skmtc.dev/roveapi/apis/rove-api.md) · [All operations](https://skmtc.dev/roveapi/apis/rove-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roveapi/apis/rove-api/revisions/0e5d69bde586?raw)