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

# Domain Lifecycle: Status, Expiry, and Fulfillment

> Understand how domains move through active, expiring_soon, expired, and failed states, and what pending fulfillment means for new registrations.

Every domain in NameGrid moves through a defined set of statuses from the moment you register it to the moment it expires or is renewed. Understanding these states — and what happens behind the scenes during registration fulfillment — helps you build reliable workflows and respond to the right signals at the right time.

## Domain statuses

The `status` field on any domain object reflects where the domain currently sits in its lifecycle.

| Status          | Meaning                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `active`        | The domain is registered and fully operational. DNS and nameserver changes take effect normally.                                      |
| `expiring_soon` | The domain is approaching its expiry date. If `autoRenew` is enabled, a renewal will be triggered automatically before expiry.        |
| `expired`       | The domain has passed its expiry date. It may be at risk of being released to the public registry — renew immediately to recover it.  |
| `failed`        | Registration or renewal failed at the registrar level. No credits were permanently deducted. Contact support if this status persists. |

<Info>
  Poll `GET /v1/domains/{domain}` to monitor status changes, or build renewal logic that checks for `expiring_soon` and triggers a manual renewal if you prefer not to rely on auto-renew.
</Info>

## Registration fulfillment

When you call `POST /v1/domains`, two things happen immediately:

1. **Credits are reserved** — the cost of registration is atomically debited from your workspace balance.
2. **The domain name is locked** — no other registrant can claim the name while NameGrid processes the order.

Actual registration with the upstream registrar happens asynchronously after the API responds. During this window, the domain may carry `"pendingFulfillment": true` on DNS record and nameserver responses.

<Note>
  `pendingFulfillment: true` does **not** mean your changes were lost. Any DNS records or nameserver updates you make while fulfillment is in progress are queued and applied automatically the moment provisioning completes. You don't need to resubmit them.
</Note>

In practice, fulfillment is fast — most domains are fully provisioned within minutes. You can safely proceed with DNS configuration immediately after registration.

## Expiry and renewal

Each domain has an `expiresAt` timestamp that marks the exact moment it expires. To avoid losing a domain, you must renew it before that time.

* **Auto-renew** — set `autoRenew: true` on a domain and NameGrid will automatically renew it before expiry, provided your workspace has sufficient credits.
* **Manual renewal** — call `POST /v1/domains/{domain}/renew` at any time to extend the domain yourself.
* **Early renewal** — renewing before the expiry date never loses you time. The new expiry is calculated from the **later** of "now" or the current `expiresAt`, so you always get a full renewal period on top of whatever time remains.

<Tip>
  If you're renewing a batch of domains, check your credit balance first with `GET /v1/account`. A single insufficient-credits error mid-batch will leave some domains renewed and others not.
</Tip>

See the [Renew a Domain](/guides/renew-domain) guide for a step-by-step walkthrough of the renewal flow.

## Auto-renew and WHOIS privacy

Both `autoRenew` and `privacyEnabled` are toggleable at any time by sending a `PATCH /v1/domains/{domain}` request. You don't need to wait for a renewal cycle or contact support.

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

* **`autoRenew`** — when enabled, NameGrid renews the domain automatically before it expires. Requires a sufficient credit balance at renewal time.
* **`privacyEnabled`** — when enabled, your personal contact information is replaced with NameGrid's privacy proxy details in public WHOIS lookups, protecting you from spam and data harvesting.

<Info>
  WHOIS privacy takes effect immediately after you enable it. The public WHOIS record is updated within minutes of the `PATCH` request completing.
</Info>