# Forward a domain (https://developer.godaddy.com/en/docs/api-users/manage-domains/forwarding)

***

title: Forward a domain
description: Create, read, update, and delete HTTP redirect rules on a domain or subdomain via the v2 forwarding API.
agentNotes:
permissions: \["Domain Owner"]
scopes: \["domains.domain:read", "domains.domain:update"]
rateLimit: "Rate-limited per credential per window. Go to /docs/api-users/rate-limits for current values."
idempotent: true
destructive: false
failureRecovery: "PUT is idempotent — replaying yields the same rule. DELETE is safe; a subsequent GET returns 404. Verify current state via GET before retrying ambiguous errors."
related:
apis:

* title: "Domains v2 — Forwarding"
  href: "/docs/references/rest/domains/v2/manage-domain-settings"
  guides:
* title: "Manage DNS records"
  href: "/docs/api-users/manage-domains/dns"
* title: "Registered domains"
  href: "/docs/api-users/manage-domains/list"
  concepts:
* title: "Handle errors"
  href: "/docs/api-users/errors"

***

## 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.

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](https://developer.godaddy.com/docs/api-users/auth) with `domains.domain:read` and `domains.domain:update` scopes
* Your GoDaddy shopper ID (`CUSTOMER_ID`) (located in your [GoDaddy account settings](https://sso.godaddy.com))

## 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:

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

```js tab="Node"
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());
```

```python tab="Python"
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())
```

```go tab="Go"
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):

```json
{
  "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:

```bash tab="curl"
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/"
  }'
```

```js tab="Node"
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
```

```python tab="Python"
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
```

```go tab="Go"
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:

```bash
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:

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

```js tab="Node"
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
```

```python tab="Python"
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
```

```go tab="Go"
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 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](https://developer.godaddy.com/docs/api-users/errors).

## Reference

* [v2 forwarding operations](https://developer.godaddy.com/docs/references/rest/domains/v2/manage-domain-settings)

## Next