Register a domain

Overview

This guide covers registering a domain programmatically using the GoDaddy Domains API.

Registration charges the account's billing method and isn't reversible. Make sure you have a payment method on file before registering.

Prerequisites

• a GoDaddy account with a payment method on file
  Note

  Go to Create account to create a GoDaddy account and add or update payment methods.

• a PAT with domains.domain:create scope
• a registrant contact with name, email, phone, and mailing address
• a confirmed available domain
• (optional) the GoDaddy CLI installed and configured

Register a domain

v3 separates pricing from execution. You get a price quote first, locking a quoteToken, then execute the registration with that token. This ensures the price you agreed to is the price charged. Always poll at least once even if the initial response appears synchronous.

Check availability

Confirm the domain is available before quoting.

• Run the availability check:

  curlNodePythonGo

  curl -s "https://api.godaddy.com/v3/domains/check-availability?domain=example.com" \
    -H "Authorization: Bearer $GODADDY_PAT"

Get a registration quote

POST /v3/domains/registration-quotes locks the price and returns the requiredAgreements list you need for the next step. The quoteToken guarantees the price you see is the price charged at registration.

• Get a quote:

  curlNodePythonGo

  curl -s -X POST "https://api.godaddy.com/v3/domains/registration-quotes" \
    -H "Authorization: Bearer $GODADDY_PAT" \
    -H "Content-Type: application/json" \
    -d '{"domain": "example.com", "period": 1}'

  {
    "quoteToken": "qt_abc123...",
    "expiresAt": "2026-01-15T10:45:00.000Z",
    "requiredAgreements": [
      {
        "agreementType": "API_DPA",
        "title": "API Domain Purchase Agreement",
        "url": "https://www.godaddy.com/agreements/showdoc?pageid=reg_sa"
      }
    ],
    "items": [
      {
        "domain": "example.com",
        "period": 1,
        "price": {
          "currencyCode": "USD",
          "value": 1199
        }
      }
    ]
  }

Review the required agreements

The quote response includes a requiredAgreements list (the legal agreements you need to review before you submit the registration). Each item has a title for display and a url linking to the full legal text.

1. Display each agreement to the user:

   NodePythonGo

   for (const agreement of requiredAgreements) {
     console.log(`Review: ${agreement.title}`);
     console.log(`Full text: ${agreement.url}`);
   }

2. After the user confirms, capture the agreement types and consent timestamp:

   NodePythonGo

   const agreedAt = new Date().toISOString();
   const agreedTypes = requiredAgreements.map((a) => a.agreementType);

Submit the registration

Send the quoteToken and consent to execute the registration. Always include an Idempotency-Key header — if the request times out or returns 5xx, replay with the same key and the server deduplicates.

• Submit the registration request:

  curlNodePythonGo

  curl -s -X POST "https://api.godaddy.com/v3/domains/registrations" \
    -H "Authorization: Bearer $GODADDY_PAT" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d '{
      "quoteToken": "qt_abc123...",
      "domain": "example.com",
      "period": 1,
      "consent": {
        "agreedAt": "2026-01-15T10:30:00.000Z",
        "agreementTypes": ["API_DPA"]
      }
    }'

Poll the operation

The registration is asynchronous. Poll the returned registrationId URL every few seconds until the status reaches a terminal state.

• Poll for the registration status:

  curlNodePythonGo

  curl -s "https://api.godaddy.com/v3/domains/registrations/{registrationId}" \
    -H "Authorization: Bearer $GODADDY_PAT"

Use the CLI

After you set up the CLI (see the CLI reference for the full command list):

1. Check availability:

   gddy domain available example.com

2. Quote the domain:

   gddy domain quote example.com

3. Register the domain:

   gddy domain purchase example.com --agree --confirm

   Registration is paid and not reversible. Run without --agree first to review the required agreements, and use --dry-run to preview before confirming.

   Use gddy domain contacts init to save default contacts for repeated purchases — the command writes a local contacts.toml template that the purchase command can use.

Registration body fields

The following table lists the fields required for the registration body.

Consent object fields

The following table lists the fields required for the consent object.

Common errors

The following table lists common errors and recommended actions. Go to Errors for the full error envelope.

Additional information

• v3 Registrations — POST /v3/domains/registrations
• v3 Registration Quotes — POST /v3/domains/registration-quotes
• v3 Operations — GET /v3/domains/operations/{operationId}
• v1 registration and renewals — POST /v1/domains/purchase

Last updated on