Get auto top-up configuration | ToAPIs Documentation

GET

/api/v1/account/billing/auto-topup

Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.

See Getting started for authentication, pagination, and errors.

Behavior

Only a main account can read its own billing. Subaccounts receive HTTP 403. A main account cannot read member billing through this endpoint.

enabled is the configuration switch; status also reflects pauses, missing cards, verification, and retries. threshold_credits is the trigger threshold and configured_amount_usd is the configured USD amount, not a promise of final payment or credited funds. Unknown times are null. reason can be card_unbound, charge_failed, verification_required, failure_limit, missing_payment_method, billing_not_linked, configuration_review_required, or null. action_required indicates interactive handling is needed. GET never attempts a charge.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.

Parameters

This endpoint accepts no path or query parameters and requires no request body.

requestExample

curl --request GET \
  --url 'https://toapis.com/api/v1/account/billing/auto-topup' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://toapis.com/api/v1/account/billing/auto-topup",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const url = new URL("https://toapis.com/api/v1/account/billing/auto-topup");

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictional data and assume credits_per_usd="100". Use the conversion rate returned by the API.

codeinteger

Numeric result code; 0 means success.

messagestring

Response message; empty on success. Error messages are localized.

dataobject

Result object for this query.

data.enabledboolean

Auto top-up configuration switch, separate from runtime status.

data.statusstring

Auto top-up runtime state, including active, paused, verification, missing-card, or retry states. Values: active, paused, requires_action, missing_payment_method, retry_wait.

data.threshold_creditsstring

Balance threshold that triggers auto top-up, in credits. Returned as a decimal string to preserve precision.

data.configured_amount_usdstring

Configured auto top-up amount in USD, not a promise of final charge or credited funds. Returned as a decimal string to preserve precision.

data.last_attempt_atstring | null

Most recent auto top-up attempt time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.last_success_atstring | null

Most recent successful auto top-up time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.next_retry_atstring | null

Next scheduled auto top-up retry time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.action_requiredboolean

Whether user interaction is needed. This GET does not initiate payment.

data.reasonstring | null

Reason code for the auto top-up state; null when none is provided.

data.sourcestring

Data source. Local configuration or ledger snapshots do not imply live Stripe state. Fixed value: "local_configuration".

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "enabled": true,
    "status": "active",
    "threshold_credits": "100",
    "configured_amount_usd": "10",
    "last_attempt_at": "2026-11-01T08:00:00Z",
    "last_success_at": "2026-11-01T08:01:00Z",
    "next_retry_at": null,
    "action_required": false,
    "reason": null,
    "source": "local_configuration"
  }
}