---
title: "Renew a domain"
method: POST
path: "/api/domains/{domain}/renew"
tags: ["Domains"]
---

# Renew a domain

`POST /api/domains/{domain}/renew`

## Request

- Base URL: `https://domani.run`
- URL: `https://domani.run/api/domains/{domain}/renew`
- Auth: HTTP bearer

Renew a domain you own for additional years (1-10). Payment is charged upfront. The new expiry date is returned in the response. When the domain's registrar refuses the renewal (renewed in the last 30 days, or a term it does not sell), the request fails with 400 RENEWAL_NOT_ELIGIBLE before any charge. The price is `renewal_price` from GET /api/domains/{domain} times `years`: send that total as `max_price` so a price change fails before any charge.

## Path parameters

- `domain` string, required

## Request body

- object
  - `years` integer: Number of years to renew (default 1)
  - `payment_method` 'card' | 'usdc' | 'balance': Payment method: 'card' (default), 'usdc', or 'balance' (marketplace credit).
  - `payment_tx` string: Transaction hash of a USDC payment already sent on-chain.
  - `payment_chain` 'base' | 'ethereum': Chain the USDC payment was sent on.
  - `max_price` number: Ceiling in USD for the renewal charge. If the real price exceeds it, the request fails with 400 PRICE_ABOVE_MAX and nothing is charged. The error's `price` field is the total to accept; confirm it with the user before retrying with that max_price.

## Response `200`

Domain renewed

- object
  - `domain` string, required
  - `renewed_years` integer, required
  - `new_expiry` string, date-time, required
  - `price` number, required
  - `currency` string, required
  - `payment_method` string, required
  - `payment_tx` string

## Other responses

- `400`: Invalid request parameters
- `401`: Missing or invalid API key
- `402`: Payment required
- `404`: Domain not found
- `429`: Rate limit exceeded - wait and retry
- `503`: REGISTRAR_CREDIT: no registrar that sells the name has the prepaid credit for this renewal right now and none could be topped up. Nothing was charged; retry later.

---

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