# Automatic refill

> Buy credit packs automatically when the balance runs low, with a monthly cap, and what happens when a charge fails.

Automatic refill buys credit packs for you when the organization's balance runs low, so running machines aren't stopped for billing. It charges the **default card** saved at the payment provider.

## Settings

| Field | Meaning |
| --- | --- |
| `enabled` | Whether refill runs. Off by default. |
| `threshold_micros` | Refill when the balance (trial + plan + credits) drops below this. Default $5. |
| `credit_packs` | $20 packs bought per refill, 1 to 50. Default 1. |
| `monthly_cap_micros` | The most refill charges per UTC calendar month, counting pending and confirmed charges. It must cover at least one refill. Default $100. |

Every member can read the settings; Owners and Billing members change them. All four fields are required when changing them:

```sh
curl -X PUT "$VMYARD_API_URL/v1/billing/auto-refill" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "threshold_micros": 10000000, "credit_packs": 2, "monthly_cap_micros": 120000000}'
```

The read (`GET /v1/billing/auto-refill`) also returns `amount_micros` (one refill), `charged_this_month_micros`, `consecutive_failures`, `disabled_reason`, and `last_charge` (`status` `pending`, `submitted`, `succeeded`, or `failed`, with `failure_code`). The console's **Automatic refill** card on the Billing page shows the month's charges against the cap, the last charge, and any failures.

## Turning it on

Enabling refill needs a payment method VMYard can charge without you present:

| Status | Code | What to do |
| --- | --- | --- |
| 409 | `billing_customer_missing` | No purchase has linked a payment customer yet. Buy credits or a plan once, then turn refill on. |
| 409 | `payment_method_missing` | There's no default card at the payment provider. Add one in the payment portal (**Manage payment** on the Billing page), then turn refill on. |
| 503 | `billing_unavailable` | Online payments aren't configured on this deployment. |
| 502 | `payment_provider_error` | The payment provider didn't answer. Try again in a minute. |

## Charges

Credits are added only when the payment provider confirms the charge, so a refill can show as **submitted** for a short while. A charge whose outcome stays unknown is retried, and fails after repeated tries.

When a charge **fails** (for example the card is declined, or needs the cardholder to confirm it), new charges pause for 2 hours, Owners and Billing members get the `auto_refill_failed` [email alert](/docs/guides/email-alerts), and the failure is counted. A successful charge resets the count.

> [!WARNING]
> After **3** failed charges in a row, refill turns itself off: `enabled` becomes `false` and `disabled_reason` is `payment_failures`. Update the card in the payment portal, then turn refill back on; that also clears the failure count.