Guides

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:

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, and the failure is counted. A successful charge resets the count.