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



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

<Callout type="warn" title="v2 only">
  Domain forwarding is v2-only. There is no equivalent in the v1 namespace.
</Callout>

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

<Tabs items={['curl', 'Node', 'Python', 'Go']}>
  <>
    <Tab value="curl">
      ```bash
      curl -s "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \
        -H "Authorization: Bearer $GODADDY_PAT" \
        -H "Accept: application/json"
      ```
    </Tab>

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

    <Tab value="Python">
      ```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())
      ```
    </Tab>

    <Tab value="Go">
      ```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)
      }
      ```
    </Tab>
  </>
</Tabs>

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:

<Tabs items={['curl', 'Node', 'Python', 'Go']}>
  <>
    <Tab value="curl">
      ```bash
      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/"
        }'
      ```
    </Tab>

    <Tab value="Node">
      ```js
      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
      ```
    </Tab>

    <Tab value="Python">
      ```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
      ```
    </Tab>

    <Tab value="Go">
      ```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
      }
      ```
    </Tab>
  </>
</Tabs>

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:

<Tabs items={['curl', 'Node', 'Python', 'Go']}>
  <>
    <Tab value="curl">
      ```bash
      curl -s -X DELETE "https://api.godaddy.com/v2/customers/$CUSTOMER_ID/domains/forwards/example.com" \
        -H "Authorization: Bearer $GODADDY_PAT"
      ```
    </Tab>

    <Tab value="Node">
      ```js
      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
      ```
    </Tab>

    <Tab value="Python">
      ```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
      ```
    </Tab>

    <Tab value="Go">
      ```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
      }
      ```
    </Tab>
  </>
</Tabs>

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

<Callout type="warn" title="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.
</Callout>

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

<Cards>
  <Card title="DNS records and nameservers" description="Manage DNS records on a domain's zone or change authoritative nameservers." href="/docs/api-users/manage-domains/dns" />
</Cards>