How to dynamically create sites with custom subdomain

TLDR; according to your documentation: “Netlify DNS can automatically turn your deployed branches into their own subdomains.” However, this does NOT appear to be the case. It seems like this is manual-- we must log into the netlify UI and manually do this for every subdomain. Am I missing something?

Longer story: this was all a complicated workaround for us to get around 2 netlify limitiations:

  1. Deploy preview branches always use
  2. URLs interfere with our credentialed cookies-- the sessionId always gets nuked and our deployments log us out of our backend on every reload.

So-- if either of the 2 above items has a fix, you can skip the first question.

Back to the first question: we just registered a new domain JUST so we could get some kind of custom subdomain support for our pull requests or branches.

So-- I’m looking for any way to make this happen automatically… is there some way to configure a custom subdomain when we deploy? Do we need to wait for the branch to deploy the first time to configure the subdomain? Is there any way to have the cookies stop interfering with our cookies?

Basically what we want is this:

  1. Developer opens pull request (but acceptable alternative = we push a new branch)
  2. Developer does no additional work and in a few minutes we’ve got a netlify site that works properly with our cookies.

We are willing to write some github actions or whatever is needed but we’d like to know how to do it.

Hi @uooq,

I’m afraid, the first point of your list doesn’t have a fix (yet). Previews will continue to use at least for the time being.

However, I’m not sure why subdomain will cause some error with the cookies. Could you elaborate on that?

As far as the other question is concerned, Netlify will be able to add automatic branch subdomains for any domain using Netlify DNS. This would be any domain registered with Netlify, or any domain correctly setup using Netlify’s nameservers. Once it’s done, you just need to push a new branch to Netlify and you’d have a subdomain on your domain with the branch name.

This won’t work if you’re using external DNS.

1 Like

Yes, I’ve delegated a domain to netlify DNS and associated with a site. When I push a branch, it doesn’t automatically get set up with the custom domain, instead I get this in the UI. This is not automatic. How do I make it automatic for all branches?

For some reason, when we serve our web ui from, our own cookies get reset.

In production, we set our own app cookies at the 2-level subdomain level so that our frontend can use the cookies with a couple of different backend servers we have. When we save our cookies using the domain, they don’t get set in the browser. If we use a custom domain or if we use a three level domain for our cookies, this doesn’t happen. If we move to the full hostname for the cookies, the auth breaks for requests to our other servers.

I don’t know why we can’t save cookies for If you can explain that, it will fix our problem.

Oh yeah, my bad. It appears subdomains cannot be automatically configured.

Oh when you put it this way, the problem might be clear. It’s basically because falls under the Public Suffix List:

Browsers do this to increase security. They won’t allow you to save a cookie for * because of the list. This is so that, if you actually save a cookie for *, it would actually be applicable for all websites on Netlify which would be a security risk.

So-- can we get back to the original question?

The docs say that I can automatically create branch sites with a custom subdomain. How do I set this up. I’ve only figured out how to do it by pushing a button manually. What’s the automatic method?

Hi, @uooq. I believe the “automatically” here was used to mean that the required DNS records are created automatically.

I do understand that this made is seem that no action would be required to make the branch subdomains but that is not the case. It does always require a manual step in the web UI (or via API call) to make the branch subdomains when using Netlify DNS.

WHAT?!? in what way does taking a MANUAL step mean AUTOMATIC?!

I create DNS records all the time by pressing buttons. There’s nothing automatic about it.

Is there at least API or CLI support for doing this so I can write some CI tools to take care of it? (I asked this question in the first request-- and now a week later and several emails later I’m still hoping to get an answer on this-- it’s like pulling teeth to get you to answer questions!!)


there is an API reference you can look into here, to see if you can accomplish what you are trying to do the way you are describing:

i hope that’s helpful.

i also hope that you will, from now on, reconsider your tone. This is not the first thread in which we have heard complaints from you that were demanding, and rude. We can tolerate (and maybe even understand) your frustration, but we are human, and to continue to spend time in these forums, speaking in a neutral tone to us is going to be required.

We are a small support team of 8 for hundreds and thousands of customers with millions of sites. We do our best, and sometimes it takes us a little while to get to you, but when we do, are try our best to be polite and kind no matter the stress we are all under.


Before I ever started this support thread I had already read your documentation. I do not know how to do this via the APi. I cannot find documentation in your api docs for “how to tell netlify to assign a custom domian name to a branch deployment or a deploy preview”

Please send a link to the instructions for THAT not just for the overall API docs.

Hi, @uooq. This the API call made using cURL:

curl '<ZONE SLUG HERE>/dns_records' \
 -H 'Content-Type: application/json' -H 'Authorization: Bearer <AUTH KEY HERE>' \
 --data-raw '{"hostname":"<BRANCH SLUG HERE>.<SITE PRIMARY DOMAIN HERE>","type":"NETLIFY","value":"https://<BRANCH SLUG HERE>--<SITE SUBDOMAIN HERE>","site_id":"<SITE API ID HERE>"}'

The JSON above is pretty printed as:

  "type": "NETLIFY",
  "site_id": "<SITE API ID HERE>"

You would also need to make a second API call with a type of NETLIFYv6 if the DNS zone has IPv6 support enabled. That second API call is made identically besides the single change of NETLIFY to NETLIFYv6.

Here is a more real world example of that API call with simulated values instead of placeholders. The values for each place holder are:

branch slug: branch-testing
site primary domain:
site Netlify subdomain: adjective-name-abc123
site API ID: e9efb98c-c680-4a57-8d29-a41944e81234
zone slug: example_com
auth key: redacted for obvious reasons

That makes the cURL example this:

curl '' \
 -H 'Content-Type: application/json' -H 'Authorization: Bearer <AUTH KEY HERE>' \
 --data-raw '{"hostname":"","type":"NETLIFY","value":"","site_id":"e9efb98c-c680-4a57-8d29-a41944e81234"}'

Again, here is the pretty printed JSON below:

  "hostname": "",
  "type": "NETLIFY",
  "value": "",
  "site_id": "e9efb98c-c680-4a57-8d29-a41944e81234"

Again, a second call with "type": "NETLIFYv6" is also required if IPv6 support is enabled for the domain.

If there are other questions about this, please let us know.