> ## Documentation Index
> Fetch the complete documentation index at: https://docs.namegrid.org/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/domains/{domain}/renew — Renew a Domain Name

> POST /v1/domains/{domain}/renew — Extend a domain's registration by 1–10 years. Credits are debited atomically at the stored renewal rate.

Use this endpoint to extend the registration period of a domain you own. You can add between 1 and 10 years in a single request, and credits are debited atomically at the renewal rate stored for your workspace at the time of the request. The new expiry date is always calculated from the later of the current expiry or the current date, so renewing early never causes you to lose time on your existing registration.

## Request

**Method:** `POST`\
**Path:** `/v1/domains/{domain}/renew`

| Header         | Required | Value              |
| -------------- | -------- | ------------------ |
| `x-api-key`    | Yes      | Your API key       |
| `Content-Type` | Yes      | `application/json` |

### Path Parameters

<ParamField path="domain" type="string" required>
  The domain name to renew (e.g. `example.com`).
</ParamField>

### Body Parameters

<ParamField body="years" type="integer">
  The number of years to extend the domain's registration by. Must be between `1` and `10`. Defaults to `1` if omitted.
</ParamField>

<Note>
  Renewal extends the expiry from the later of "now" or the current expiry date. If your domain expires on 2027-01-04 and you renew today, you get a full year added on top of the existing expiry — you don't lose any time you've already paid for.
</Note>

### Request Example

```bash theme={null}
curl -X POST https://api.namegrid.org/v1/domains/example.com/renew \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "years": 1 }'
```

## Response — 200 OK

<ResponseField name="domain" type="object">
  A summary object for the renewed domain, including the updated expiry date.

  <Expandable title="domain fields">
    <ResponseField name="name" type="string">
      The domain name that was renewed.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the domain after renewal (typically `active`).
    </ResponseField>

    <ResponseField name="years" type="integer">
      The number of years added by this renewal.
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      ISO 8601 timestamp reflecting the new expiry date after the renewal extension is applied.
    </ResponseField>
  </Expandable>
</ResponseField>

```json theme={null}
{
  "domain": {
    "name": "example.com",
    "status": "active",
    "years": 1,
    "expiresAt": "2028-01-04T12:00:00.000Z"
  }
}
```

<Warning>
  Credits are debited immediately when the renewal succeeds. Renewals cannot be reversed once the updated registration period has been confirmed with the registry.
</Warning>

## Errors

| Status | Reason                                                                           |
| ------ | -------------------------------------------------------------------------------- |
| `400`  | `years` is outside the allowed range of 1–10                                     |
| `402`  | Insufficient credits — response includes `balance` (your current credit balance) |
| `404`  | The domain does not exist or is not owned by your workspace                      |