Guides

Payments & the wallet

All prices are EUR, quoted retail, per year, and VAT-inclusive — the number you are quoted is the number you pay. The quote you act on comes from GET /api/v1/check (registration) or GET /api/v1/tlds (register / renew / transfer per TLD).

The wallet

Every workspace has a wallet; every purchase debits it. Fund it either way:

Top up — dashboard → Billing → Top up (Stripe Checkout). The balance is credited when the payment completes.

Pay as you go — pass a payment instrument on the spending call itself:

{
  "domain": "example.com",
  "duration": 1,
  "confirm_price": 18,
  "payment_method": "pm_…"
}

The exact price is charged, credited to the wallet, and debited by the purchase — net card movement equals the price, no standing balance needed. shared_payment_token is accepted in place of payment_method for agent frameworks that issue Stripe shared payment tokens.

`confirm_price`

Spending verbs (POST /domains, POST /domains/{name}/renew, POST /domains/{name}/transfer) require confirm_price — the total you were quoted (unit price × duration for multi-year operations). The server re-resolves the live price and compares within €0.01:

Match → the operation proceeds and the wallet is debited on success.
Mismatch → 409 price_changed with both prices in details; nothing is charged. Re-quote and retry with the current price if it's acceptable:

{ "error": "price_changed", "details": {
  "message": "The price has changed. Re-check before purchasing.",
  "confirmed_price": 18, "current_price": 21, "currency": "EUR" } }

Failure semantics — why there are no refunds to wait for

The order of operations is: charge (if pay-as-you-go) → credit wallet → verify balance → registry action → debit wallet. If the registry action fails, the debit never happens: the money stays as wallet credit and the retry uses it without touching your card again. You are never waiting on a refund to retry.

If the wallet can't cover the price and no payment instrument was passed, you get 402 insufficient_balance with required and available amounts in cents — top up or attach a payment method and retry.

Auto-renew

Auto-renew is on by default and is billed from the wallet like any other purchase, just without a confirm_price — the setting is the consent, at the renewal price listed in GET /api/v1/tlds.

About 30 days before expiry the domain is renewed for a year and the wallet is debited; the invoice covers the year appended to the current expiry.
If the wallet can't cover it, the renewal is retried daily. Still unpaid 10 days before expiry, it is dropped and the domain is left to expire — top up and renew by hand (POST /domains/{name}/renew) to keep it.
Turning auto-renew off before the charge (PATCH /domains/{name}/settings with auto_renew: false) costs nothing. After the charge the renewal stands and is not refunded; turning it off stops the following year, and the response carries renewed_until.
Turning it on inside those last 30 days renews right away.

A renew call for a term that is already being bought answers 409 renewal_in_progress.

Seeing what's coming

GET /api/v1/domains/{name} carries a renewal object — the same one the MCP get_domain tool and domains settings <domain> render:

{ "renewal": {
  "auto_renew": true,
  "expires_at": "2026-10-31", "billed_until": "2026-10-31",
  "next_charge_at": "2026-10-01", "price": 18, "currency": "EUR",
  "follows_registry": false, "charge_lead_days": 30, "phase": "idle",
  "term": null } }

next_charge_at is the day the wallet is charged, price what it costs.
billed_until is what you have already paid for — past the expiry while a paid renewal is still being processed at the registry.
term appears once the renewal has been attempted. state: "awaiting_funds" with reason: "insufficient_balance" carries shortfall — the EUR to top up; the charge is retried daily until 10 days before expiry. state: "lapsed" means it was dropped: renew by hand. state: "refunded" means we charged you but the registry did not perform the renewal: the full amount is back on your balance and the domain is not renewed, so renew it by hand if you still want it.
follows_registry: true (workspaces billed by arrangement) means nothing is charged ahead of the registry — it renews and you are billed afterwards, so there is no next_charge_at.

Invoices and history

Every purchase ends up on an invoice, visible under Billing in the dashboard along with the full balance history. Each line names the operation and the domain (Registration: example.com (2y)) and carries the service period that operation bought — for a renewal, the term appended to the existing expiry, not the date you paid.

By default each purchase gets its own invoice, issued as soon as it completes. Workspaces can instead be invoiced daily, weekly or monthly, in which case every purchase in the period is drawn onto one invoice shortly after the period ends. Either way the lines are the same; only the document they arrive on differs. Ask us to change the period for your workspace.

Topping up is not itself a purchase, so it produces a Stripe payment receipt rather than an invoice: at that moment nothing has been supplied yet. The per-purchase invoices are the tax documents, and prices are VAT-inclusive — the figure you confirm through confirm_price is the figure debited and the figure on the invoice, with any VAT broken out inside it.

Business customers: set your workspace's default contact to an organization contact and fill in its VAT number. That number goes onto your invoices, and for EU businesses outside our country it applies reverse charge (0% VAT). An individual default contact is invoiced as a consumer.

Paying on credit

By arrangement, a workspace can be put on credit instead of prepaid: there is no balance to keep topped up, purchases go straight through, and the invoice for them is a real open invoice you pay like any other — that payment is how the money reaches us, so nothing is deducted from a balance. Spending is bounded by an agreed credit limit; a purchase that would cross it is refused with 402 insufficient_balance, carrying the remaining credit in available. Settle an open invoice, or ask us to raise the limit.

Authentication Transfers