> ## 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.

# Renew a Domain Registration with the NameGrid API

> Manually renew a domain, extend registration for up to ten years, and configure auto-renew to protect against expiry using the NameGrid API.

Keeping your domains renewed is critical to staying online. NameGrid gives you two ways to handle renewal: trigger it manually whenever you choose, or enable auto-renew so NameGrid handles it for you before expiry. This guide covers both approaches and shows you how to monitor upcoming expiry dates across your portfolio.

## Manual renewal

Send a `POST` request to `/v1/domains/{domain}/renew` to renew a domain immediately. The renewal deducts credits from your account balance atomically — no credits are charged unless the operation fully succeeds.

Renewing early never wastes time on your registration. The new expiry date is always calculated by extending from the **later** of today or the domain's current expiry, so you never lose the time you already paid for.

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

**Response**

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

The response shows the updated `expiresAt` timestamp confirming how far out the registration now runs.

**Options**

* **`years`** — The number of years to extend the registration. Defaults to `1`. Accepts values from `1` to `10`.

<Warning>
  If your credit balance is insufficient to cover the renewal cost, the API returns a **402 Payment Required** error with `required` and `balance` fields showing the shortfall. No credits are charged. Top up your balance at [https://app.namegrid.org](https://app.namegrid.org) and retry.
</Warning>

## Enabling auto-renew

Auto-renew instructs NameGrid to renew your domain automatically before it expires, as long as your account has enough credits. Enable it by sending a `PATCH` request to `/v1/domains/{domain}` with `autoRenew` set to `true`.

```bash theme={null}
curl -X PATCH https://api.namegrid.org/v1/domains/yourdomain.com \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "autoRenew": true }'
```

**Response**

```json theme={null}
{ "autoRenew": true, "privacyEnabled": true }
```

To disable auto-renew at any time, send the same request with `"autoRenew": false`.

<Tip>
  Keep your credit balance topped up to make sure auto-renew can always succeed. If your balance is too low when the renewal attempt runs, the domain will not be renewed and could expire.
</Tip>

## Checking expiry dates

Use `GET /v1/domains` to list all domains in your account along with their `expiresAt` timestamps, giving you a full view of what needs attention.

```bash theme={null}
curl https://api.namegrid.org/v1/domains \
  -H "x-api-key: ng_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

Domains that are approaching their expiry date automatically transition to an `expiring_soon` status in the response. Filter for this status to build renewal reminders or automated workflows that act before a domain lapses.

<Note>
  NameGrid also sends email notifications to the address on your account as expiry approaches. Renewing early — whether manually or via auto-renew — is always the safest option.
</Note>