What Is sellers.json? A Guide for Site Owners

sellers.json is a file that ad systems such as supply-side platforms and exchanges publish to say who the sellers behind their account IDs are. It is not a file a site owner uploads; the one you control is ads.txt. For bloggers, news publishers and other site owners earning from ads, sellers.json matters because it lets you check that the IDs in your own ads.txt lines point to the right company on the other side.

The IAB Tech Lab sellers.json page (Opens in a new tab) says the expectation is that SSPs and exchanges post their sellers.json files for buyers to review. The page has no section written for publishers, since its guidance is aimed at SSPs and buyers.

Two files, two owners

Confusing the two files is understandable, because both are about who may sell your ad space. They differ in who writes them and what question they answer.

What you publish: ads.txt

The IAB ads.txt page (Opens in a new tab) describes ads.txt as a simple, flexible and secure method that publishers and distributors can use to publicly declare the companies they authorize to sell their digital inventory. Its stated aims are more transparency in programmatic advertising and making it harder for bad actors to profit from counterfeit inventory. Version 1.1 adds two values, OWNERDOMAIN and MANAGERDOMAIN, which support the seller relationships shown in sellers.json. For the publisher side of setup, see the ads.txt setup guide; the file discussed here is its counterpart.

What the ad system publishes: sellers.json

According to the IAB Tech Lab specification, sellers.json provides a mechanism for buyers to discover who the entities are that are either direct sellers of or intermediaries in the selling of digital advertising. The file lives with the advertising system, not with you. The specification says every advertising system listed in an ads.txt file, and every system referenced from a SupplyChain object node, should publish a sellers.json file at its own domain.

Where each file lives

Your ads.txt sits in the root directory of your site, and the AdSense ads.txt help page (Opens in a new tab) confirms this with the example that the root for example.com is example.com/ads.txt. The ad system’s file is reached at its domain under /sellers.json over HTTP or HTTPS, served with a JSON content type, and HTTPS is preferred. You can open both in a browser.

Note: The specification cited below is version 1.0 from July 2019. IAB Tech Lab can update its standards, so check the current page before relying on a detail.

Anatomy of a seller record

The version 1.0 specification (Opens in a new tab) defines a top-level object with a list of sellers, a version string and optional contact details and identifiers such as TAG-ID or DUNS. Each seller record carries these fields. Knowing them lets you read a record without guessing.

seller_id and one-to-one identity

The specification states that it is invalid for a seller_id to represent multiple entities. Every seller_id maps to a single entity paid for inventory under that ID, while one entity may have several seller_ids inside the same ad system. If you ever see your ID next to two different companies, that contradicts the specification and is worth asking your partner about.

What the three seller types mean

PUBLISHER indicates that the inventory sold through the account is on a site, app or other medium owned by the named entity, and that the advertising system pays that entity directly. INTERMEDIARY indicates that the inventory is not owned by the named entity or that the advertising system does not pay it directly. BOTH means both kinds of inventory are transacted by the seller. The field should be treated as case insensitive.

Confidential and passthrough records

When is_confidential is 1, the identity is confidential and name and domain may be omitted, yet all sellers must still be listed. A passthrough seller facilitates inventory between an upstream supplier and the consumer of that inventory; the specification says the supplier must hold an account-control relationship with the consuming system. Neither flag is something a publisher edits. They help you understand why a record may look sparse.

The gap sellers.json was built to close

The introduction of the specification explains the reason in plain terms. Ads.txt has been very successful at letting publishers define who is authorized to sell their impressions, but it makes no attempt at revealing the identities behind publisher account IDs on the advertising platform.

Inconsistent bid request fields

The specification says the final seller can currently be identified through the Publisher name and domain attributes of a bid request, but in practice these properties are inconsistently populated by various selling systems. A published sellers.json lets that identity be looked up in one consistent place.

Smaller requests through offline lookups

Both the IAB page and the specification note that this information can be looked up and cached offline rather than carried in every bid request. For buyers that means smaller requests; for you it means a record change may not be seen everywhere at once. Consuming systems should cache the file and periodically verify freshness, and if there are no cache directives the default expiry is 7 days.

The SupplyChain object

The IAB page defines the SupplyChain object as an OpenRTB extension that lets buyers see all parties selling or reselling a given bid request, built mainly from nodes, one per entity. Buyers can verify the identifiers in those nodes against sellers.json files. The page also says buyers should continue to target inventory sold through ads.txt and app-ads.txt channels.

DIRECT and RESELLER: where the documents stop

A reader may be tempted to map the DIRECT and RESELLER words in ads.txt lines onto the PUBLISHER and INTERMEDIARY types in sellers.json. The IAB and AdSense pages do not support that mapping. The AdSense help page shows an example ads.txt line containing DIRECT, but it does not explain the word and never mentions RESELLER. The IAB ads.txt page does not mention either relationship. So do not build a one-to-one table of your own; ask your ad partner how they classify an account.

What the sources do tie together is the ID. The seller_id in sellers.json is the same ID that appears in ads.txt. That shared identifier is the dependable bridge between the two files.

A look-up routine for site owners

Practical suggestion: this routine uses only what the specification defines and does not require access to anything you do not own.

1. Open your ads.txt and list each ad system domain and the account ID next to it.
2. For each domain, try opening its /sellers.json path in a browser.
3. If the file opens, search it for your account ID in the seller_id field.
4. When you find a match, compare seller_type, name and domain with what you expect from your contract.
5. If the record is flagged confidential, accept that name and domain can be missing.
6. If no record turns up, copy the ID again from the ads.txt line and retry before drawing any conclusion.

After these steps you can answer one question: does each ID in my ads.txt connect to the company I expect on the other side? A yes means the half of the chain you can see is consistent. A no means moving to the next section.

Checklist

• Your ads.txt is reachable from the site root and each line is well formed.
• Each ad system’s /sellers.json address has been tried.
• A seller_id match was searched for every account ID.
• The seller_type fits the account.
• Name and domain fit the expected company, or the record is flagged confidential.
• Mismatches are logged with date and screenshot.
• Messages to the partner are saved.

A log you can reuse

The specification does not cover file size, update schedules or access limits for individual ad systems. If a file fails to open, that does not by itself mean something is wrong on your side. The specification says that when a server responds with a 404 or another HTTP error, the last successfully retrieved data set should be used, so a one-off browser result should not be treated as final.

When a record looks wrong

A record can look wrong in three ways: the legal entity is not the one you expect, the type differs from what you expect, or it points to a company you do not recognize. None of these gives you the ability to edit the file, because the ad system controls it.

Decision rule

First confirm that your ads.txt line carries the right ID, since a mistyped ID leads to someone else’s record. If the ID is correct and the record is still inconsistent, ask the partner. The specification lets a file include a contact email for questions or inquiries about the file; if one is present it is a sensible first address, and if not, use the partner’s regular support channel. If the record names a company you do not know, review who you have authorized and what contracts you hold, and do not keep an ads.txt line whose origin you cannot explain.

What to put in the message

Practical suggestion: include your domain, the full ads.txt line, the sellers.json address, the record you saw and the record you expected. Add the date. Phrase it as questions, such as which entity this ID belongs to and why the type is what it is, rather than as accusations.

Waiting for the fix to show

Because consuming systems cache the file, with a default of 7 days when no directive is present, a corrected record may take time to be visible everywhere. Wait a reasonable period before rechecking and note the result with the date.

Example scenario: a photography blog changes partners

Example scenario: A hobby photography blog moves its ad management to a specialist company. The company adds a line to the blog’s ads.txt. The owner opens the ad system’s sellers.json, searches the ID and finds a record whose legal entity name is an older business name of the owner, not the management company. The owner does not try to change anything. A short message goes to the company with the ads.txt line and the record, asking why the name and type appear as they do. The answer either leads to an updated record or explains the arrangement. The owner also checks that the lines for the previous partner are still in ads.txt, and asks whether that partner should still be authorized.

The order of operations is the lesson: verify your own line, read the other side, then direct the question to the right channel.

Why it is worth the effort

The IAB frames ads.txt as a way to increase transparency and make counterfeit inventory harder to sell. Sellers.json supplies the other half, which is knowing who an ID belongs to. For a site owner, the practical value is confirming that sales made under your ID are attributed to the entity you expect.

Sellers.json and revenue

None of the IAB or AdSense pages says that a sellers.json record affects revenue, fill rate or how much buyers bid on a specific site. The IAB page says buyers continue to target inventory sold through ads.txt and app-ads.txt channels and can review the SupplyChain object and verify identifiers in sellers.json files. How that behavior changes a given publisher’s earnings is not described. Do not promise that fixing a record raises income. For revenue metric definitions, read the RPM, eCPM and fill rate guide.

Managing both files during a partner change

A change of ad partner is a moment when the two files can drift apart. Practical suggestion: this sequence keeps them aligned.

1. Save a dated copy of the current ads.txt.
2. Ask the new partner for the exact ads.txt line in writing.
3. Check that the new partner’s sellers.json opens and shows your ID with the type and name your contract implies.
4. Agree on a written switch date with both partners.
5. Remove lines for partners you no longer work with once the switch date passes.
6. Re-run the look-up routine and log the date.

Practical suggestion: if an old partner’s record remains visible on the other side, allow for cache delay and ask the old partner.

Who is responsible for what

You are responsible for what you place in your own ads.txt: which companies you authorize and under which contracts. The ad system is responsible for the content of its sellers.json. The specification says all sellers must be included even if confidential, an obligation directed at the ad system. If an unexpected line appears in your ads.txt that you did not add, treat it as an access-control problem on your own site and review who can edit that file.

Reading a sample file line by line

The specification ends with a sample file, which makes a good practice text. It begins with a contact email, a postal address, the version number and a TAG-ID identifier, followed by the list of sellers. One sample record is a publisher whose type is PUBLISHER. Another is an exchange whose type is INTERMEDIARY. A third pair shows the same selling company with two seller_ids and a comment field distinguishing regions. A hybrid seller is marked BOTH with a comment saying it sells its own and other sellers’ inventory. One record has only an ID, the INTERMEDIARY type and is_confidential set to 1, so it carries no name or domain. The last record is a passthrough publisher with is_passthrough set to 1 and a comment explaining that the buyer must establish an account relationship.

Reading that sample teaches three habits. First, the comment field is the quickest way to learn what an ID represents. Second, one company may legitimately appear several times with different IDs and types. Third, a record with no name is not necessarily broken. These habits transfer to real files you open, with one caution: the sample is illustrative, and real files follow whatever the ad system has published.

Questions to put to an ad partner

• Which entity does my account ID belong to in your sellers.json?
• How is my account classified, PUBLISHER, INTERMEDIARY or BOTH, and why?
• Is the record for my ID marked confidential, and is that intended?
• When a record is corrected, how long until it is visible in your published file?
• Who is the right contact for questions about the file?

Keep the answers with the log entry for that partner. If the responses differ from what the specification describes, for instance one ID attributed to several entities, say so politely and ask for clarification.

Common reading errors

• Typing the wrong domain: the specification speaks of a root domain and subdomains as needed, so confirm the exact host.
• Copying an ID with stray characters, which breaks the match.
• Treating a confidential record as an error when the specification allows it.
• Mixing up PUBLISHER and INTERMEDIARY, which describe different relationships to the inventory.
• Reading a cached or failed response as final.
• Assuming a publisher can edit another company’s file.

This list is not a certification test. When in doubt, ask the partner instead of changing your own ads.txt on a guess.

Frequently Asked Questions

Do I need to create a sellers.json file for my site?

No. According to the IAB Tech Lab page, SSPs and exchanges are expected to post sellers.json files. The file a site owner publishes is ads.txt. For a publisher, sellers.json is something to read and cross-check.

What is the difference between ads.txt and sellers.json?

Ads.txt lets a publisher declare which companies are authorized to sell its inventory. Sellers.json lets an advertising system declare who the sellers behind its account IDs are. The specification says ads.txt does not reveal the identities behind publisher account IDs, and sellers.json fills that gap.

Is an INTERMEDIARY record bad for me?

The specification defines INTERMEDIARY as inventory not owned by the named entity or an entity the advertising system does not pay directly. The specification does not call it good or bad; check whether it matches how your account really works.

Are DIRECT and RESELLER the same as PUBLISHER and INTERMEDIARY?

Neither page defines that mapping. The AdSense help page shows DIRECT only in an example line and never mentions RESELLER. Ask your ad partner how they classify accounts.

Can I fix a wrong seller record myself?

No. The file sits at the ad system’s domain and the ad system maintains it. You can verify the ID in your ads.txt line and ask the partner about the record. The specification notes that a file may include a contact email for questions about it.

Will correcting sellers.json raise my ad income?

Neither page makes such a claim. They describe transparency and verification goals, so no income promise should be made.

Conclusion

Sellers.json is the ad system’s file and the counterpart to your ads.txt: one states who may sell, the other states who is behind an ID. A site owner’s job is to take each ID from ads.txt, look it up in the partner’s file, and confirm that the type and entity match expectations. If they do not, the right move is a documented question to the partner, not an edit to your own ads.txt on a guess. The mapping between DIRECT and RESELLER on one side and PUBLISHER and INTERMEDIARY on the other is not defined, so do not assume it.

Practical suggestion: when you cannot tell whether a mismatch is a real problem or only a cache delay (the specification’s default expiry for consuming systems is about 7 days), note the date you first saw it and recheck before escalating, so the partner can check their publication history. Keep a dated log, recheck after any partner change, and make no promise that a record fix changes revenue. To compare ad inventory options, see the Akua Adforce ad spaces page; scope and terms are listed there.