---
title: "Your auto top-up settings"
method: GET
path: "/v1/auto-topup"
tags: ["Accounts"]
---

# Your auto top-up settings

`GET /v1/auto-topup`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/auto-topup`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Whether auto top-up is on, the balance that triggers it and the amount it adds, a summary of the saved card, whether it is paused and why, and the 10 most recent attempts. available is false when auto top-up cannot be used on this platform right now. It is turned on with a top-up on the dashboard, which saves the card; it cannot be changed with an API key.

Requires `account:r`.

## Response `200`

Auto top-up settings, saved card summary, pause state and recent attempts.

- AutoTopup: Your auto top-up: the settings, the saved card, whether it is paused and why, and recent attempts.
  - `available` boolean, required: False when auto top-up cannot be used on this platform right now. The other fields still describe your settings.
  - `enabled` boolean, required: Whether auto top-up is on. It can be on and paused (paused_at).
  - `threshold_cents` integer, nullable, required: When your balance falls below this, in CAD cents, your card is charged. Null before auto top-up was first turned on.
  - `amount_cents` integer, nullable, required: The credit each auto top-up adds, in CAD cents, before tax. Always at least threshold_cents, so one top-up brings the balance back up to it. Null before auto top-up was first turned on.
  - `card` object, nullable, required: The saved card auto top-up charges. Null when none is saved.
    - `brand` string, required
    - `last4` string, required
    - `exp_month` integer, required
    - `exp_year` integer, required
  - `paused_at` string, date-time, nullable, required: When auto top-up was paused. Nothing is charged while it is paused. You resume it with "Top up to resume" in the Auto top-up section of the dashboard's Billing page, which is a new top-up that saves your card again. A pause for ACCOUNT_REVIEW cannot be resumed that way (see paused_reason).
  - `paused_reason` 'DECLINED' | 'AUTHENTICATION_REQUIRED' | 'EXPIRED_CARD' | 'CARD_REMOVED' | 'BILLING_ADDRESS' | 'ACCOUNT_REVIEW' | 'ADMIN' | 'REFUND' | 'CHARGE_LIMIT' | 'null', nullable, required: Why it was paused: the card was declined, needed authentication, expired or was removed; the billing address could not be used for tax; a payment was refunded and taken off the balance (REFUND); it reached its limit of 3 charges in 24 hours (CHARGE_LIMIT); the account is under review; or HonkIO staff paused it. You resume from every reason except ACCOUNT_REVIEW with "Top up to resume" on the dashboard. You cannot resume from ACCOUNT_REVIEW yourself. The account.auto_topup_paused webhook event carries the same value as reason.
  - `cap_blocked` boolean, required: True while auto top-up is skipping charges because one would go over your balance or 30-day top-up limit.
  - `setup_pending` boolean, required: True when a setup was started and not finished: settings were chosen on the dashboard and the top-up that saves the card has not completed. They take effect only when it does. False once it completes, and after the settings are edited or auto top-up is turned off.
  - `monthly_rent_cents` integer, required: Monthly rent of the numbers you hold, in CAD cents. Auto top-up also tops up ahead of rent due within a day.
  - `attempts` AutoTopupAttempt[], required: The 10 most recent attempts, newest first.
    - `id` string, required: ata_…
    - `trigger` 'threshold' | 'rent', required: threshold: the balance fell below threshold_cents. rent: the balance was below the number rent due within 24 hours.
    - `status` 'pending' | 'succeeded' | 'failed' | 'skipped_cap', required: skipped_cap: not charged, because the top-up would have gone over your balance or 30-day top-up limit.
    - `amount_cents` integer, required: The credit added to your balance, in CAD cents.
    - `tax_cents` integer, nullable, required: Sales tax charged on top of amount_cents, in CAD cents. Null when no tax was calculated.
    - `total_cents` integer, nullable, required: What the card was charged, in CAD cents: amount_cents plus tax_cents. Null before the charge is made.
    - `failure_code` string, nullable, required: Why a failed attempt failed: a card code such as card_declined or expired_card, or platform_error when the failure was on HonkIO's side (auto top-up is not paused and tries again). Attempts that charged nothing and paused nothing (abandoned, not_needed) are never shown.
    - `created_at` string, date-time, required
    - `settled_at` string, date-time, nullable, required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: The API key lacks the permission this operation requires, or the account is suspended or closed.
- `429`: Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).
- `500`: Unexpected server error.

---

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