Skip to main content
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.
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.

​
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.
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.
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.
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.
See the Renew a 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.
  • 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.
WHOIS privacy takes effect immediately after you enable it. The public WHOIS record is updated within minutes of the PATCH request completing.