Create, read, update, and delete HTTP redirect rules on a domain or subdomain via the v2 forwarding API.

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 your GoDaddy shopper ID.

v2 only

Domain forwarding is v2-only. There is no equivalent in the v1 namespace.

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 GoDaddy shopper ID (CUSTOMER_ID) (located in your GoDaddy account settings)

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"

const pat = process.env.GODADDY_PAT;
const customer = process.env.CUSTOMER_ID;
const res = await fetch(
  `https://api.godaddy.com/v2/customers/${customer}/domains/forwards/example.com`,
  {
    headers: {
      Authorization: `Bearer ${pat}`,
      Accept: "application/json",
    },
  },
);
if (res.status === 404) throw new Error("No forwarding rule set");
console.log(await res.json());

import os, requests

customer = os.environ["CUSTOMER_ID"]
res = requests.get(
    f"https://api.godaddy.com/v2/customers/{customer}/domains/forwards/example.com",
    headers={
        "Authorization": f"Bearer {os.environ['GODADDY_PAT']}",
        "Accept": "application/json",
    },
)
if res.status_code == 404:
    print("No forwarding rule set")
else:
    print(res.json())

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    customer := os.Getenv("CUSTOMER_ID")
    url := fmt.Sprintf(
        "https://api.godaddy.com/v2/customers/%s/domains/forwards/example.com",
        customer)
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
    req.Header.Set("Accept", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    if res.StatusCode == 404 {
        fmt.Println("No forwarding rule set")
        return
    }
    var rule map[string]any
    json.NewDecoder(res.Body).Decode(&rule)
    fmt.Println(rule)
}

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/"
  }'

const pat = process.env.GODADDY_PAT;
const customer = process.env.CUSTOMER_ID;

const res = await fetch(
  `https://api.godaddy.com/v2/customers/${customer}/domains/forwards/example.com`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${pat}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      fqdn: "example.com",
      type: "REDIRECT_PERMANENT",
      url: "https://www.example.com/",
    }),
  },
);
console.log(res.status); // expect 204

import os, requests

customer = os.environ["CUSTOMER_ID"]
res = requests.put(
    f"https://api.godaddy.com/v2/customers/{customer}/domains/forwards/example.com",
    json={"fqdn": "example.com", "type": "REDIRECT_PERMANENT", "url": "https://www.example.com/"},
    headers={
        "Authorization": f"Bearer {os.environ['GODADDY_PAT']}",
        "Content-Type": "application/json",
    },
)
print(res.status_code)  # expect 204

package main

import (
    "bytes"
    "fmt"
    "net/http"
    "os"
)

func main() {
    customer := os.Getenv("CUSTOMER_ID")
    body := bytes.NewReader([]byte(
        `{"fqdn":"example.com","type":"REDIRECT_PERMANENT","url":"https://www.example.com/"}`))
    req, _ := http.NewRequest("PUT",
        fmt.Sprintf("https://api.godaddy.com/v2/customers/%s/domains/forwards/example.com", customer),
        body)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))
    req.Header.Set("Content-Type", "application/json")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    fmt.Println(res.StatusCode) // expect 204
}

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"

const pat = process.env.GODADDY_PAT;
const customer = process.env.CUSTOMER_ID;

const res = await fetch(
  `https://api.godaddy.com/v2/customers/${customer}/domains/forwards/example.com`,
  {
    method: "DELETE",
    headers: { Authorization: `Bearer ${pat}` },
  },
);
console.log(res.status); // expect 204

import os, requests

customer = os.environ["CUSTOMER_ID"]
res = requests.delete(
    f"https://api.godaddy.com/v2/customers/{customer}/domains/forwards/example.com",
    headers={"Authorization": f"Bearer {os.environ['GODADDY_PAT']}"},
)
print(res.status_code)  # expect 204

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    customer := os.Getenv("CUSTOMER_ID")
    req, _ := http.NewRequest("DELETE",
        fmt.Sprintf("https://api.godaddy.com/v2/customers/%s/domains/forwards/example.com", customer),
        nil)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("GODADDY_PAT"))

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    fmt.Println(res.StatusCode) // expect 204
}

Forwarding rule fields

Field	Required	Description
`fqdn`	Yes	The domain or subdomain to forward (e.g. `example.com` or `shop.example.com`). Must match the `{fqdn}` path parameter.
`type`	Yes	Redirect type — see table below.
`url`	Yes	Destination URL (must be a valid `http://` or `https://` URL).
`mask`	No	Masking options when `type` is `MASKED`.

Redirect types

Type	HTTP code	Description
`REDIRECT_PERMANENT`	301	Permanent redirect. Search engines transfer link equity to the target. Use for long-term or permanent moves.
`REDIRECT_TEMPORARY`	302	Temporary redirect. Search engines retain the source URL's link equity. Use for short-term redirects.
`MASKED`	—	The browser loads the target URL but the original FQDN stays visible in the address bar. Uses an inline frame.

Masked forwarding and SEO

Masked forwarding prevents the destination URL from appearing in the browser address bar by loading it in a frame. It isn't appropriate for most use cases and can harm SEO. Prefer REDIRECT_PERMANENT or REDIRECT_TEMPORARY unless masking is specifically required.

Common errors

Status	Most likely cause
`403`	Credential lacks write access to this domain.
`404`	Domain doesn't exist, isn't owned by the authenticated account, or no forwarding rule exists (for GET/DELETE).
`409`	Domain status prevents the operation (e.g. domain is in a pending transfer).
`422`	Invalid `fqdn`, invalid destination URL, or unrecognized `type` value.

Full error envelope: Errors.

Reference

v2 forwarding operations

DNS records and nameservers

Manage DNS records on a domain's zone or change authoritative nameservers.

Agent & Automation Notes

PermissionsDomain Owner

Scopesdomains.domain:read, domains.domain:update

Rate limitRate-limited per credential per window. Go to /docs/api-users/rate-limits for current values.

IdempotentYes

DestructiveNo

On failurePUT is idempotent — replaying yields the same rule. DELETE is safe; a subsequent GET returns 404. Verify current state via GET before retrying ambiguous errors.

API References

Domains v2 — Forwarding

Guides

Concepts

Handle errors

Last updated on

Forward a domain