How to forward a domain

Overview

Domain forwarding creates an HTTP redirect rule for a fully-qualified domain name (FQDN) — the root domain or a subdomain. When a browser requests the FQDN, the registrar returns a redirect to the target URL. Use forwarding to redirect a root domain to www, point a subdomain to an external URL, or set up temporary redirects during a site migration.

Forwarding operations use the v2 API at /v2/customers/{customerId}/domains/forwards/{fqdn}. The customerId path parameter is a UUID (not the numeric shopper ID). Go to Find your customer ID for the lookup that returns it.

Prerequisites

The following prerequisites are required before you manage forwarding rules:

• A GoDaddy account with at least one registered domain
• A Personal Access Token with domains.domain:read and domains.domain:update scopes
• Your customer ID (CUSTOMER_ID), which the next section explains how to find

Find your customer ID

The customerId path parameter is a UUID. It isn't the numeric shopper ID that your GoDaddy account settings display, and passing the shopper ID where a customerId belongs returns 403.

GET /v1/shoppers/{shopperId} returns the UUID when you ask for it through the includes query parameter. The following procedure retrieves it.

• Send the request:

curl -s "https://api.godaddy.com/v1/shoppers/$GODADDY_SHOPPER_ID?includes=customerId" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Accept: application/json"

Read customerId from the response:

{
  "shopperId": "123456789",
  "customerId": "1e8a4b2c-7f3d-4c91-b60e-2f5d8c9a1b34",
  "email": "dev@example.com",
  "nameFirst": "Ada",
  "nameLast": "Lovelace",
  "marketId": "en-US"
}

The UUID doesn't change for the life of the account. Resolve it once and store it instead of looking it up per request. Go to Shoppers for the full operation reference.

Find your customer ID

The customerId path parameter is a UUID. It isn't the numeric shopper ID that your GoDaddy account settings display, and passing the shopper ID where a customerId belongs returns 403.

GET /v1/shoppers/{shopperId} returns the UUID when you ask for it through the includes query parameter. The following procedure retrieves it.

• Send the request:

curl -s "https://api.godaddy.com/v1/shoppers/$GODADDY_SHOPPER_ID?includes=customerId" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Accept: application/json"

Read customerId from the response:

{
  "shopperId": "123456789",
  "customerId": "1e8a4b2c-7f3d-4c91-b60e-2f5d8c9a1b34",
  "email": "dev@example.com",
  "nameFirst": "Ada",
  "nameLast": "Lovelace",
  "marketId": "en-US"
}

The UUID doesn't change for the life of the account. Resolve it once and store it instead of looking it up per request. Go to Shoppers for the full operation reference.

Export the UUID as CUSTOMER_ID before running the examples in the following sections.

Read a forwarding rule

Returns the DomainForwarding object for the FQDN. Returns 404 if no forwarding rule is configured for that FQDN.

The following procedure reads a forwarding rule for an FQDN.

• Run the following command for your preferred language:

curl -s "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Accept: application/json"

Response (DomainForwarding object):

{
  "fqdn": "example.com",
  "type": "REDIRECT_PERMANENT",
  "url": "https://www.example.com/"
}

Returns 404 if no forwarding rule is configured for the FQDN.

Create or replace a forwarding rule

PUT /v2/customers/{customerId}/domains/forwards/{fqdn} creates the rule if it doesn't exist, or replaces it if it does. The call is idempotent — replaying the same request produces the same rule.

The following procedure creates or replaces a forwarding rule.

• Run the following command for your preferred language:

curl -s -X PUT "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "fqdn": "example.com",
    "type": "REDIRECT_PERMANENT",
    "url": "https://www.example.com/"
  }'

Returns 204 No Content on success.

Forward a subdomain

The fqdn path parameter accepts any FQDN on a domain you own. The same PUT pattern applies — just change the fqdn path parameter and body field to the subdomain:

curl -s -X PUT "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/shop.example.com" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "fqdn": "shop.example.com",
    "type": "REDIRECT_PERMANENT",
    "url": "https://store.example.com/"
  }'

Delete a forwarding rule

Removes the forwarding rule for the FQDN. Returns 204 No Content. After deletion, browsers visiting the FQDN no longer receive a redirect.

The following procedure deletes a forwarding rule.

• Run the following command for your preferred language:

curl -s -X DELETE "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \
  -H "Authorization: Bearer $GODADDY_PAT"

Forwarding rule fields

Redirect types

Common errors

Full error envelope: Errors.

Reference

• v2 forwarding operations

Next

Last updated on