# Turn on automatic top-up

> Let Coritan charge your default payment method when your credit balance falls below a threshold you choose.

Source: https://www.coritan.com/docs/billing/automatic-top-up/

Hourly services draw on your credit as they run, and Coritan suspends them when the credit runs out. Automatic top-up adds credit for you: when your balance falls below a threshold, Coritan charges your default payment method a fixed amount. New accounts start with it off.

## Before you begin

- Sign in to the [dashboard](https://www.coritan.com/dashboard).
- Save a payment method that Coritan can charge without you, such as a card or a PayPal account ([Manage payment methods](/docs/billing/payment-methods/)). Coritan charges your default method, or the method you saved most recently when none is the default.
- Your account pays in advance. Automatic top-up does not run on an account that Coritan bills afterwards.

## Turn it on

1. In the sidebar, select **Billing**, then the **Payment methods** tab.
2. Turn on the **Keep credit topped up** switch at the top of its card.
3. In **When my balance drops below**, enter the balance that starts a top-up, in US dollars.
4. In **Add**, enter how much to add each time, in US dollars. It must be at least $1.
5. Select **Save changes**.

To turn it off, turn off the switch and select **Save changes**.

## Result

A message confirms the setting, for example `Auto top-up turned on: $50.00 whenever the balance drops below $25.00.` The **Overview** tab of **Billing** shows the same rule under your balance.

Coritan checks balances every 15 minutes by default. When yours is below the threshold, it charges the amount to your default method, adds it to your balance and emails you a receipt. It tops up at most once an hour, so one top-up that leaves you under the threshold is not followed by another straight away. The top-up appears on the **Transactions** tab as `Auto top-up $50.00`.

When an hourly service is about to be suspended for lack of credit, Coritan tries a top-up first ([How hourly billing works](/docs/billing/hourly-billing/)).

The charge is made in the currency your payment method was saved in ([Currencies and countries](/docs/billing/currencies-and-regions/#what-each-payment-is-charged-in)).

## Troubleshooting

`Enter $0 or more.`
: The threshold is negative or not a number.

`Enter at least $1.`
: The amount to add is below $1 or not a number.

**Could not save auto top-up**
: The setting did not save. The message under it gives the reason. Try again.

**Could not load your auto top-up settings**
: The card did not load. Select **Try again**.

A top-up did not happen
: Coritan emails you when an automatic top-up fails, once until the next one succeeds. The usual causes are a declined card and no saved method. Check the email, update your method on the **Payment methods** tab, or [add credit](/docs/billing/add-credit/) yourself.

## Related

- [Add credit to your balance](/docs/billing/add-credit/)
- [How hourly billing works](/docs/billing/hourly-billing/)
- [Manage payment methods](/docs/billing/payment-methods/)

## With the API

Read the setting with [`GET /billing/topup/config`](/docs/api/reference/client/billing/#op-get-api-v1-billing-topup-config):

```bash
curl https://api.coritan.com/api/v1/billing/topup/config \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "auto_topup_enabled": true,
  "auto_topup_threshold": "25.0000",
  "auto_topup_amount": "50.0000",
  "credit_balance": "37.0100",
  "total_deposited": "125.0000",
  "hourly_billing_unlocked": true
}
```

The amounts are US dollars, as decimal strings. `total_deposited` is all the credit you have added, and `hourly_billing_unlocked` says whether you can order hourly services.

Change it with [`PUT /billing/topup/config`](/docs/api/reference/client/billing/#op-put-api-v1-billing-topup-config). `enabled` is required; `threshold` (`0` or more) and `amount` (`1` or more) are optional and keep their values when you leave them out.

```bash
curl -X PUT https://api.coritan.com/api/v1/billing/topup/config \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold": "25", "amount": "50"}'
```

```json
{"message": "Auto top-up configuration updated"}
```

A value out of range answers `422`.

## API

- `GET /api/v1/billing/topup/config`: Get topup config (https://www.coritan.com/docs/api/reference/client/billing/#op-get-api-v1-billing-topup-config)
- `PUT /api/v1/billing/topup/config`: Update topup config (https://www.coritan.com/docs/api/reference/client/billing/#op-put-api-v1-billing-topup-config)