What is sellers.json, and what does it tell a buyer?
Part of Supply path transparency
The short answer
sellers.json is a public JSON file that each exchange or SSP posts at its root domain, listing every seller account it pays. For each seller_id it states the seller type, PUBLISHER, INTERMEDIARY or BOTH, and the legal name and business domain unless the seller is confidential. Buyers join it to ads.txt to learn who is actually paid.
Key takeaways
- sellers.json is the exchange's own directory, one entry per seller account, keyed by the same ID that appears in ads.txt and in SupplyChain nodes.
- IAB Tech Lab's OpenRTB Working Group finalized sellers.json and the SupplyChain object for industry adoption on July 31, 2019.
- Every seller must be listed, confidential ones included, and each seller_id must map to exactly one legal entity that is paid.
- For an intermediary, the domain field should point to that seller's own sellers.json, so a buyer can follow a resold path one hop at a time.
- A sound cross check runs both ways: from the site's ads.txt line to the exchange's entry, then from the entry's domain back to the site's OWNERDOMAIN.
Why does sellers.json exist when ads.txt already lists sellers?
ads.txt tells a buyer which accounts a publisher authorizes, but not who stands behind each account number. The sellers.json specification (opens in a new tab) fills that gap. Its introduction notes that bid requests can carry Publisher.name and Publisher.domain, but that in practice selling systems populate them inconsistently. A file that buyers look up and cache offline keeps bid requests smaller and lets them identify the final seller and every intermediary.
Definition
- sellers.json
- A JSON file an advertising system publishes at its root domain that lists every seller account it represents, with each account's seller_id, seller type and, unless confidential, the name and business domain of the legal entity it pays.
According to IAB Tech Lab's sellers.json page (opens in a new tab), the OpenRTB Working Group finalized sellers.json and the SupplyChain object for industry adoption on July 31, 2019. The specification asks every advertising system listed in an ads.txt file, and any system referenced from a SupplyChain node, to publish the file at its own domain under /sellers.json, served as application/json. Publishers do not publish sellers.json; the systems that pay them do.
What is inside a sellers.json file?
The file is one parent object that holds a sellers array plus a few facts about the advertising system itself. A buyer can jump straight to the sellers array, but the parent fields answer useful questions about the system: who to contact about an entry, and which business identifiers it carries.
| Attribute | Required | What the specification says |
|---|---|---|
| sellers | Yes | The list of all seller objects the system represents; all sellers must be included even if they are confidential |
| identifiers | No | Name and value pairs for the advertising system, such as a TAG-ID or a Dun & Bradstreet DUNS number |
| contact_email | No | An address for questions about the file |
| contact_address | No | The business address of the advertising system |
| version | Yes | The version of the specification; the only valid value is 1.0 |
Inside the sellers array, two rules keep entries meaningful. It is invalid for one seller_id to represent several entities: each ID maps to a single legal entity that is paid for inventory sold under it. The reverse is allowed: one company can hold several seller_ids in the same system. The specification's own sample shows a company with separate IDs for owned and operated inventory in North America, owned inventory in Asia Pacific, and resold inventory, each explained in the optional comment field.
How should a buyer read seller_type, name and domain?
The specification defines PUBLISHER narrowly: the inventory is on a site, app or other medium owned by the named entity and the advertising system pays them directly. INTERMEDIARY covers inventory the named entity does not own, or cases where the system does not pay them directly. The name is required unless the seller is confidential, and the domain is required when the seller has a web presence and is not confidential. Domains are root domains, never full URLs.
| Entry | What it tells the buyer | Next step |
|---|---|---|
| PUBLISHER, with name and domain | The named owner of the inventory is paid directly on this account | Compare the domain with the OWNERDOMAIN in the site's ads.txt |
| INTERMEDIARY, with domain | Someone other than the owner is paid; the domain should be the root of that seller's own sellers.json | Open that seller's sellers.json and find the next account on the path |
| BOTH | The seller transacts owned and resold inventory through this account | Use OWNERDOMAIN and the comment field to tell which kind this site is |
| is_confidential set to 1 | Name and domain may be withheld, but the entry must still exist | Record the path as unnamed and look for a named path to the same site |
| is_passthrough set to 1 | The seller has an account control relationship with the downstream system | If it is the last link, the buying system needs that relationship to transact |
How do buyers cross check sellers.json against ads.txt?
A two way check for one ads.txt line
- Open the system's file. Take the domain in the first field of the ads.txt line and fetch /sellers.json from it.
- Find the seller_id. Search the sellers array for the account ID from the second field. If it is missing, the path cannot be confirmed from the exchange side.
- Compare the type with the relationship. A DIRECT line normally pairs with a PUBLISHER or BOTH entry; a DIRECT line on an INTERMEDIARY entry is a question for the publisher.
- Match the domain back to the site. Following the implementation guide's logic, an entry whose domain equals the site's OWNERDOMAIN is the owner, one that equals its MANAGERDOMAIN is the manager, and any other domain is a reseller of the inventory.
- Follow intermediaries one hop. For an INTERMEDIARY entry, open the sellers.json at its domain and repeat until the owner appears or the trail goes confidential.
What does a sellers.json check look like on a real plan?
Fictional example
A home solar installer buying across Texas
A fictional home solar installer wants a curated deal on Texas sites about home improvement, energy bills and storm preparation. The trading desk has a shortlist and runs the two way check on every DIRECT line before sending the list to the exchange.
A Houston home improvement site passes cleanly: its ads.txt lists the exchange as DIRECT, the exchange's sellers.json types that account PUBLISHER, and the entry's domain equals the OWNERDOMAIN in the site's file. A San Antonio energy news site lists a DIRECT line whose entry is typed INTERMEDIARY under a sales house's domain. The site's file names no MANAGERDOMAIN, so the desk asks the publisher which company really controls the account before using that path.
An Austin do it yourself blog lists an account the exchange's sellers.json does not contain at all. The desk keeps the blog on the list through its other confirmed path and asks the exchange's support team about the missing entry.
How does PlacementGraph use sellers.json when it checks a site?
What mistakes do buyers make when reading sellers.json?
Access rules differ from ads.txt in one important way. For ads.txt, a 404 means no declarations exist. For sellers.json, the specification says that a 404 or any other HTTP error means the last successfully retrieved data set should be used. A crawler that treats a temporary outage at an exchange as an empty directory will mark good paths as unconfirmed. Redirects follow the same rule as ads.txt: any number within the root domain, and at most one hop to a third party.
Reading errors to rule out before flagging a seller
- A BOTH entry was read as proof that the site is owned by the seller.
- A confidential entry was treated as unauthorized, though the specification requires confidential sellers to be listed.
- A full URL was compared with a root domain, so a real match looked like a mismatch.
- The seller_id was compared with the wrong ads.txt line because the same exchange appears several times in the file.
- An intermediary's own sellers.json was never opened, so the path stopped one hop short of the owner.
- A cached copy of the exchange's file was older than the publisher's latest ads.txt change.
Frequently asked questions
Who publishes a sellers.json file?
The advertising system does: exchanges, SSPs and any other system that is listed in a publisher's ads.txt or appears as a node in a SupplyChain object. Publishers and buyers do not publish one. Each system posts a single directory at its own root domain covering every seller it represents.
Can one company have several seller IDs on the same exchange?
Yes. The specification allows a selling entity to hold several seller_ids within one advertising system, for example to separate owned inventory from resold inventory or one region from another. What it forbids is the opposite: one seller_id shared by several entities.
What do TAG-ID and DUNS mean in a sellers.json file?
They are the two standard identifier names the specification lists for the identifiers array. TAG-ID is the advertising system's Trustworthy Accountability Group ID, and DUNS is its Dun & Bradstreet business number. They describe the system that publishes the file, not the individual sellers in it.
Does sellers.json show how much each seller keeps from a sale?
No. The specification covers identity and relationship type only: who is paid under each seller_id and whether that party owns the inventory. Fees and take rates appear nowhere in the file. They come from contracts and from log level data shared by the buying platform or the exchange.
Which version of sellers.json is current?
Version 1.0. The specification's change log dates it to July 2019, and the version attribute in the parent object has 1.0 as its only valid value. IAB Tech Lab now maintains the text in its Supply Chain Validation repository on GitHub alongside ads.txt and app-ads.txt.
Sources
- sellers.json specification (opens in a new tab)IAB Tech Lab, Supply Chain Validation repository
- Sellers.json (opens in a new tab)IAB Tech Lab
- ads.txt 1.1 Implementation Guide (August 2022) (opens in a new tab)IAB Tech Lab
- ads.txt Specification Version 1.1 (opens in a new tab)IAB Tech Lab, Supply Chain Validation repository
Researched and written by PlacementGraph Research. Read how we research, source and update these pages. Corrections: diana@placementgraph.com.