ads.txt and subdomains: which file the crawler reads and when to use subdomain=
Key takeaways
- Under the IAB ads.txt specification, crawlers fetch ads.txt from the root domain, defined as the public suffix plus one label, and strip subdomains from the URLs they crawl.
- A subdomain's own ads.txt is only crawled if the root domain's ads.txt declares it with a line such as subdomain=blog.example.com.
- When a declared subdomain has its own ads.txt, only the sellers listed in that subdomain file are authorized for the subdomain; otherwise the root file applies.
- Google says it crawls and enforces ads.txt files on subdomains where one exists and is referenced from the root domain's ads.txt.
- Google notes you only need a subdomain declaration if the authorized seller or publisher ID differs between the subdomain and the root domain.

Ad systems read ads.txt from the root domain, and that file covers every subdomain unless it explicitly delegates one. To give a subdomain its own list of sellers, add subdomain=sub.example.com to the root file and publish an ads.txt on the subdomain. Once delegated, only the subdomain’s file counts for that subdomain, so it must contain your AdSense line too.
Which ads.txt file does the crawler read for a subdomain?
The IAB Tech Lab ads.txt 1.1 specification defines the “root domain” as “the ‘public suffix’ plus one string in the name”, derived from the Public Suffix List. So:
| Site URL | Root domain the crawler uses |
|---|---|
www.example.com |
example.com |
blog.example.com |
example.com |
shop.example.co.uk |
example.co.uk (co.uk is a public suffix) |
news.example.org |
example.org |
In section 5.5, the spec says crawlers “should strip the subdomains when creating the crawler’s URL list” and should “only crawl for ads.txt files on subdomains that are listed using the ‘subdomain=’ variable in the ads.txt on the root domain.”
Google’s Ensure your ads.txt files can be crawled page says the same from the AdSense side: “Ads.txt crawling will start at the root domain.”
How does the subdomain= directive work?
SUBDOMAIN is one of the variables in ads.txt 1.1. The spec describes it as “a machine readable subdomain pointer to a subdomain within the root domain, on which an ads.txt can be found.” Two constraints:
- “Only root domains should refer crawlers to subdomains.”
- “Subdomains should not refer to other subdomains.”
Google’s Ads.txt FAQs confirm support: “Google crawls and enforces ads.txt files placed on subdomains, where one exists, and is referenced from the ads.txt file on the root domain.” Google’s example line is subdomain=subdomain.example.com.
A complete setup with a blog that uses a different seller than the main site. The root file, at https://example.com/ads.txt:
google.com, pub-0000000000000000, DIRECT, f08c47fec0942fa0
subdomain=blog.example.com
The subdomain file, at https://blog.example.com/ads.txt:
google.com, pub-1111111111111111, DIRECT, f08c47fec0942fa0
Here pub-0000000000000000 is authorized on example.com and www.example.com, and only pub-1111111111111111 is authorized on blog.example.com.
What happens with each configuration?
Section 5.5 of the spec spells out the outcome: “When the ads.txt on the root domain declares a subdomain and an ads.txt exists on that subdomain, only advertising systems listed in the subdomain ads.txt are authorized to sell inventory on that subdomain. When the ads.txt on the root domain doesn’t declare a subdomain or an ads.txt does not exist on the subdomain, only advertising systems listed in the root domain ads.txt are authorized to sell inventory on that subdomain.”
| Root file declares subdomain? | Subdomain has ads.txt? | File that governs the subdomain |
|---|---|---|
| No | No | Root file |
| No | Yes | Root file (the subdomain file is never crawled) |
| Yes | No | Root file |
| Yes | Yes | Subdomain file only |
The last row is where publishers get caught. If you declare the subdomain and its file lists only another network, your AdSense account is no longer authorized there, even if the root file lists it.
When should I use subdomain=?
Google’s note is the rule of thumb: “You only need to do this if the authorized seller or your publisher ID are different for the subdomain when compared to the root domain.”
Typical cases:
- Different AdSense accounts. A subdomain run by a partner or a separate business with its own publisher ID.
- Different networks. The main site uses AdSense only, a subdomain also uses another SSP you do not want authorized on the main site.
- Hosted sections. A subdomain operated by a platform (forum, shop, job board) where the platform sells its own inventory.
If you simply run the same AdSense account across www, blog and shop, do not declare anything. One line in the root file covers them all, and you avoid maintaining several files.
How do I delegate a subdomain, step by step?
Order matters, because the moment the root file declares the subdomain, the subdomain file becomes the only list that counts there.
- Write the subdomain file first. Include every seller that should be authorized on the subdomain, including your AdSense line if AdSense runs there.
- Publish it at
https://sub.example.com/ads.txtand confirm withcurl -sILthat it returns status 200 andtext/plainon both HTTP and HTTPS (Google crawls both schemes). - Add the declaration to the root file, one line per subdomain, using the bare hostname:
subdomain=sub.example.com. - Verify the root file still returns 200 and still contains the lines for the main site.
- Ask AdSense to recheck. On the site’s page under “Sites”, click “Check for updates”.
To undo a delegation, reverse the order: remove the subdomain= line from the root file first, and only then delete the subdomain file.
How can I see what the crawler sees?
Fetch the two files the way a crawler would, starting from the root:
curl -sL https://example.com/ads.txt | grep -i '^subdomain='
curl -sL https://blog.example.com/ads.txt
The first command lists the subdomains the root file delegates. For each one, the second command shows the only sellers authorized there. If your AdSense publisher ID is not in that output, AdSense is not authorized on that subdomain. The IAB’s open-source crawler follows subdomain= referrals the same way, which makes it useful for auditing several domains at once (see validating ads.txt yourself).
What if my site is a subdomain of a domain I don’t own?
If your site is yourname.platform.com, the root domain is platform.com, and you cannot edit its ads.txt. The Ads.txt troubleshooter gives two options for this situation: ask the owner “to host the ads.txt file on your behalf”, or “ask the service provider to set up a subdomain referral for you.” The second means the platform adds subdomain=yourname.platform.com to its root file so that your own subdomain file gets crawled.
Whether such a site can be added to AdSense at all is a separate question, covered in adding subdomains and subdirectories to AdSense.
How is this different from www?
www is a subdomain like any other, but you normally do not declare it. If your site lives on www.example.com, Google’s rule is that example.com/ads.txt must serve the file or redirect to www.example.com/ads.txt. A redirect within the root domain is allowed, and the content then counts as the root file. Do not add subdomain=www.example.com as a substitute for a working root URL; troubleshooting that case is covered in ads.txt Not found or Unauthorized.
Does app-ads.txt handle subdomains the same way?
No. The IAB app-ads.txt specification says the subdomain directive “is unused in app-ads.txt files and should be ignored if encountered.” Instead, verifiers derive the path from the developer URL in the app store: they keep the first subdomain before the registrable domain (dropping www. and m.), try https://subdomain.example.com/app-ads.txt first and fall back to https://example.com/app-ads.txt. More in app-ads.txt vs ads.txt.
Common mistakes
| Mistake | Effect | Fix |
|---|---|---|
File on the subdomain, no subdomain= in root |
Subdomain file ignored | Declare it in the root file, or move the line to the root file |
subdomain= declared, AdSense line missing in the subdomain file |
AdSense unauthorized on that subdomain | Add the AdSense line to the subdomain file |
subdomain=https://blog.example.com/ |
Value is not a hostname | Use the bare hostname: subdomain=blog.example.com |
subdomain= placed in a subdomain’s file |
Not allowed by the spec | Put all declarations in the root file |
| Subdomain file returns HTML or 404 | Falls back to the root file (per the spec) | Serve a plain-text 200 response |
After any change, use “Check for updates” on the site’s page in AdSense; Google says updates take a few days, and up to a month for sites that make few ad requests. The line format itself is covered in ads.txt syntax.
Frequently asked questions
Do I need an ads.txt file on every subdomain?
No. If the same AdSense account and the same networks monetize the subdomain, the root domain's ads.txt already covers it: the IAB specification says that when the root file does not declare a subdomain, only the sellers in the root file are authorized there. Google notes you only need a subdomain declaration when the authorized seller or publisher ID differs.
I put ads.txt on blog.example.com but AdSense ignores it. Why?
Crawlers start at the root domain and only fetch a subdomain's ads.txt if the root file points to it with subdomain=blog.example.com. Without that line, the file on the subdomain is never read and the root file governs the subdomain. Add the declaration to example.com/ads.txt, or put your AdSense line in the root file instead.
Can a subdomain refer to another subdomain?
No. The IAB ads.txt 1.1 specification says only root domains should refer crawlers to subdomains, and subdomains should not refer to other subdomains. Every subdomain= declaration therefore belongs in the root domain's file, one line per subdomain.
Does subdomain= work in app-ads.txt?
No. The IAB app-ads.txt specification says the subdomain directive is unused in app-ads.txt files and should be ignored if encountered. app-ads.txt uses its own rule for subdomains: verifiers check the first subdomain of the developer website URL, then fall back to the root domain.
Sources
- Ads.txt FAQs · Google AdSense Help
- Ensure your ads.txt files can be crawled · Google AdSense Help
- Ads.txt troubleshooter · Google AdSense Help
- Ads.txt Version 1.1 · IAB Tech Lab
- IAB Tech Lab Authorized Sellers for Apps (app-ads.txt) · IAB Tech Lab
Related guides
- ads.txt "Not found" or "Unauthorized": a technical checklist for redirects, HTTPS, status codes and robots.txt
Diagnose ads.txt Not found and Unauthorized statuses: root vs www, HTTP vs HTTPS, redirect rules, 404 and soft 404, robots.txt, content type, with curl tests.
- Adding a site to AdSense: root domain, subdomain or subdirectory?
Which URL to add to AdSense: root domain, subdomain or subdirectory, how www variants and ads.txt fit in, and how Blogger and other hosted platforms differ.
- ads.txt syntax for AdSense, line by line: pub ID, DIRECT, TAG ID, comments and variables
The AdSense ads.txt line field by field: google.com, your pub ID, DIRECT, f08c47fec0942fa0, plus comments, variables and the formatting errors that break parsing.
- app-ads.txt vs ads.txt: the developer website, store listings and how verifiers find the file
How app-ads.txt differs from ads.txt: where the file lives, how the developer website in the store listing is used, subdomain rules and crawling for app inventory.