# Overview (https://developer.godaddy.com/en/docs/references/rest/domains/v3)



## Overview

Domains v3 introduces a **quote-execute** model built for clarity and pricing predictability:

1. **Discover** — check availability and get suggestions
2. **Quote** — lock in a price with a `quoteToken`
3. **Register** — execute the registration using that token
4. **Poll** — follow the async operation to completion

All write operations return `202 Accepted` with an operation or registration ID. Poll the returned URL until status reaches `COMPLETED` or `FAILED`.

<Callout type="info" title="v3.1 scope">
  v3.1 covers domain discovery, registration, domain reads, nameserver management, and DNS records. Renewals, transfers, contact updates, forwarding, and privacy settings remain on the [v1 API](https://developer.godaddy.com/docs/references/rest/domains/v1) and [v2 API](https://developer.godaddy.com/docs/references/rest/domains/v2).
</Callout>

## Endpoint groups

<Cards>
  <Card href="/docs/references/rest/domains/v3/discovery" title="Discovery" description="Suggest domains for a keyword query and check availability of specific domains. Prices are indicative; locked pricing is only established at quote time." />

  <Card href="/docs/references/rest/domains/v3/registration-quotes" title="Registration Quotes" description="Get a locked price and a quoteToken for one or more domains. The token is required to execute registration and expires after a short window." />

  <Card href="/docs/references/rest/domains/v3/registrations" title="Registrations" description="Execute a registration using a quoteToken and poll for completion. Requires an Idempotency-Key header and a consent record." />

  <Card href="/docs/references/rest/domains/v3/domains" title="Domains" description="Read registered domain records including status, nameservers, privacy preferences, and expiry date." />

  <Card href="/docs/references/rest/domains/v3/domain-management" title="Domain Management" description="Update nameservers for a domain. Returns a DomainOperation to poll for completion." />

  <Card href="/docs/references/rest/domains/v3/records" title="DNS Records" description="List, create, replace, and delete DNS records in a GoDaddy-managed zone. Changes apply synchronously." />

  <Card href="/docs/references/rest/domains/v3/operations" title="Operations" description="Abstract poll endpoint for any async v3 operation. Equivalent to the registration-specific poll URL but usable for any operation type." />
</Cards>

## Quote-execute flow

```
GET /v3/domains/check-availability?domain={domain}
  → availability result (indicative price)

POST /v3/domains/registration-quotes
  → quoteToken (locked price, short TTL)

POST /v3/domains/registrations
  (body: quoteToken + domain + period + consent)
  → 202 Accepted, Registration entity with poll URL

GET /v3/domains/registrations/{registrationId}
  or
GET /v3/domains/operations/{operationId}
  → poll until status = COMPLETED | FAILED
```

## Conventions

| Convention           | Detail                                                                       |
| -------------------- | ---------------------------------------------------------------------------- |
| Base URL             | `https://api.godaddy.com`                                                    |
| Version prefix       | `/v3/`                                                                       |
| Async writes         | `202 Accepted` with `links[rel=self]` poll URL                               |
| Idempotency          | `Idempotency-Key` header required on registration                            |
| Indicative vs locked | Availability and suggestions return indicative prices; quotes lock the price |
| Auth                 | `Authorization: Bearer ${GODADDY_PAT}`                                       |

## What v3 does not cover

The following operations are not yet in v3. Use v1 or v2 instead:

| Operation                 | Use instead                                    |
| ------------------------- | ---------------------------------------------- |
| Domain renewals           | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) |
| Domain transfers          | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) |
| Contact updates           | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) |
| Domain forwarding         | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) |
| Privacy settings          | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) |
| List owned domains        | [Domains v1](https://developer.godaddy.com/docs/references/rest/domains/v1) |
| Shopper-scoped operations | [Domains v2](https://developer.godaddy.com/docs/references/rest/domains/v2) |