Get auto top-up configuration
Read the auto top-up configuration and run state
Note for users in mainland China: Please use https://api.toapis.cn as the API endpoint (Base URL). Replace https://api.toapis.com with https://api.toapis.cn in the examples in this document.
See Access for authentication, pagination, and errors.
Behavior
Returns the auto top-up configuration and runtime status, for troubleshooting why auto top-up did not fire. Only the main account can query its own billing; sub-accounts get HTTP 403, and a main account cannot use this endpoint to query member bills.
enabled is the user-configured switch, while status is the actual execution state and also reflects pauses, missing cards, pending verification, and retries.
threshold_credits is the balance threshold that triggers auto top-up and configured_amount_usd the configured charge amount in USD. Neither is an actual charge or credited amount. Unknown times return null.
reason explains the current state and may be card_unbound, charge_failed, verification_required, failure_limit, missing_payment_method, billing_not_linked, configuration_review_required, or null. action_required indicates the user must act.
This endpoint never initiates a charge.
Authentication
AuthorizationstringheaderrequiredUse Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.
Request parameters
This endpoint accepts no path or query parameters and requires no request body.
Request examples
requestExample
curl --request GET \
--url 'https://api.toapis.com/api/v1/billing/auto-topup' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/billing/auto-topup",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
timeout=30,
)
response.raise_for_status()
print(response.json())const url = new URL("https://api.toapis.com/api/v1/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.
codeintegerNumeric result code; 0 means success.
messagestringResponse message; empty on success. Error messages are localized.
dataobjectResult object for this query.
data.enabledbooleanAuto top-up configuration switch, separate from runtime status.
data.statusstringAuto 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_creditsstringBalance threshold that triggers auto top-up, in credits. Returned as a decimal string to preserve precision.
data.configured_amount_usdstringConfigured 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 | nullMost recent auto top-up attempt time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.last_success_atstring | nullMost recent successful auto top-up time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.next_retry_atstring | nullNext scheduled auto top-up retry time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.action_requiredbooleanWhether user interaction is needed. This GET does not initiate payment.
data.reasonstring | nullReason code for the auto top-up state; null when none is provided.
data.sourcestringData source. Local configuration or ledger snapshots do not imply live Stripe state. Fixed value: "local_configuration".
Response examples
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"
}
}