sellers.json: What SSPs Need to Know

Your sellers.json file is how DSPs see your platform.

Not your deck. Not your account manager's pitch. Your actual file, sitting at ssp-domain.com/sellers.json, updated (or not updated) at whatever cadence you run, with whatever accuracy you maintain.

DSPs cache it. They parse it. They cross-reference every bid request against it. And when your data contradicts what a publisher claims in their ads.txt, the DSP doesn't call you to ask which file is correct. The bid just fails.

The IAB Tech Lab released the sellers.json spec in July 2019 as part of the supply chain transparency initiative. It works alongside ads.txt and the SupplyChain object to give DSPs full visibility into who's actually selling what. For SSPs, it's both a compliance requirement and a competitive differentiator.

Here's what you need to know to maintain it properly.

What sellers.json Actually Does

sellers.json is the sell-side half of the two-sided verification system.

Publishers use ads.txt to declare who's authorized to sell their inventory. Your sellers.json file tells DSPs who those sellers actually are. When a DSP receives a bid request with seller_id "12345" from your platform, they check your sellers.json to confirm who holds that account.

The file structure is straightforward. It's a JSON document with an array of seller objects.

DSPs download your file daily (sometimes more frequently) and cache the data. When they evaluate bid requests, they look up seller_ids in their cached copy of your sellers.json. If the data is stale or wrong, they're making decisions based on outdated information.

The Five Fields That Matter

Every seller entry needs these fields. Missing or incorrect data creates verification failures for the publisher and reduces buyer confidence in your platform.

seller_id (required)

The unique identifier for this seller on your platform. This is the same string that appears in the publisher's ads.txt file as the account ID.

The seller_id is the link between ads.txt and sellers.json. When a publisher writes your-ssp.com, pub-12345, DIRECT in their ads.txt, that "pub-12345" must match a seller_id in your sellers.json exactly. Same format, same case, same everything.

Common mistakes: changing ID formats during platform migrations, using different IDs for the same seller across different products, or generating IDs that include special characters that break parsing.

name (required)

The legal or business name of the seller. For publishers, this should be the company name. For intermediaries, it's the network or reseller name.

DSPs use this field to identify the entity behind the seller_id. Some DSPs compare the name against business registries or other identity databases to detect fraud or misrepresentation.

Be accurate. Don't use DBA names that differ significantly from legal names. Don't use placeholder text like "Publisher Account" or "Client 123." The name should match what the seller would recognize as their own business name.

domain (required)

The business domain of the seller. For publishers, this is typically the domain where their content is hosted. For intermediaries, it's their corporate domain.

DSPs compare this field against the domain in the bid request. If a bid request claims to be selling inventory from "publisher.com" but your sellers.json shows the seller's domain as "different-domain.com," that's a red flag.

Domain mismatches happen legitimately (publisher rebrands, domain changes, multi-domain operations), but they reduce verification confidence. Keep this field current.

seller_type (required)

One of three values: PUBLISHER, INTERMEDIARY, or BOTH.

PUBLISHER: The entity owns the inventory. You pay them directly. They're the source. This corresponds to publishers who list your platform as DIRECT in their ads.txt.

INTERMEDIARY: The entity doesn't own the inventory. They're reselling it from other publishers. This corresponds to RESELLER entries in ads.txt.

BOTH: The account operates as both. The seller has their own inventory (publisher role) and also resells other publishers' inventory (intermediary role) under the same seller_id.

Accuracy is critical. If a publisher labels your relationship as DIRECT in their ads.txt but your sellers.json shows that seller_id as INTERMEDIARY, verification breaks. The DSP sees conflicting claims and can't resolve them.

is_confidential (optional, but important)

A flag indicating whether the seller's identity is hidden. When set to 1 (or true), the name, domain, and seller_type fields can be omitted or masked.

Confidential entries exist for business reasons. You want to protect the relationship. The publisher doesn't want competitors to know who they work with. But confidentiality has costs.

DSPs can't fully verify confidential sellers. They see the seller_id but not the identity. This reduces transparency, which reduces trust, which reduces SPO scores. Some DSPs automatically deprioritize or exclude paths that include confidential sellers.

Use confidential status sparingly. If you default all new sellers to confidential, you're hurting your publishers' verification scores and your own competitive position.

How DSPs Use Your sellers.json

DSPs don't treat sellers.json as a compliance checkbox. They use it as live data to evaluate and filter supply paths.

Verification

For every bid request, the DSP checks your sellers.json to confirm the seller_id exists, extract the seller's identity, and verify alignment with the publisher's ads.txt. If verification passes, the bid proceeds. If it fails, the bid is rejected or downgraded.

Verification failures happen when:

• The seller_id in the bid request doesn't exist in your sellers.json
• The seller_type conflicts with the publisher's ads.txt relationship type
• The domain field doesn't match the publisher domain in the bid request
• The entry is marked confidential and the DSP requires full transparency

SPO Algorithms

DSPs use sellers.json data to build supply path graphs. They map how many hops exist between the publisher and their platform, identify the shortest paths, and prioritize transparent paths over opaque ones.

Your sellers.json feeds directly into these algorithms. DSPs can see:

• How many of your sellers are PUBLISHER vs INTERMEDIARY (shorter paths win)
• What percentage of your sellers are confidential (transparency wins)
• How accurate your data is compared to publisher ads.txt files (accuracy wins)

An SSP with a 95% non-confidential rate and clean alignment with publisher ads.txt files scores higher than an SSP with 50% confidential entries and frequent mismatches.

Seller Reputation

Some DSPs maintain internal reputation scores for individual sellers based on historical performance. They use your sellers.json to map seller_ids to domains and track which sellers consistently deliver quality inventory.

If your sellers.json has frequent ID changes, domain updates, or missing entries, DSPs can't maintain stable reputation tracking for your sellers. This hurts the publishers on your platform who have good reputations.

Maintenance Best Practices for SSPs

Your sellers.json file isn't a set-it-and-forget-it compliance artifact. It's operational data that needs active maintenance.

Update frequently

Daily updates are the minimum for platforms with active onboarding and account changes. Real-time updates when seller data changes are ideal.

Stale sellers.json data creates verification failures for every affected publisher. If a publisher signs with you, sets up their ads.txt entry, and starts sending traffic, but your sellers.json doesn't include their account yet, every bid request from that publisher fails verification until you update the file.

Default to non-confidential

Unless there's a specific, documented reason for confidentiality, all entries should be non-confidential. Transparency is the point of the file.

If you must mark an account confidential, communicate the trade-offs to the publisher. They're accepting lower verification scores and potential SPO penalties in exchange for privacy.

Validate data accuracy

Run automated checks on your sellers.json before publishing updates:

• seller_ids are unique and match your platform's ID format
• Names are complete and accurate (not placeholder text)
• Domains resolve and match the seller's actual domain
• seller_type values are correct (PUBLISHER, INTERMEDIARY, or BOTH)
• No entries are stale or belong to closed accounts

A bad entry in your file hurts not just that one seller but your entire platform's reputation with DSPs.

Remove inactive sellers

Don't leave old entries in sellers.json indefinitely. If an account is closed or inactive for more than 90 days, remove the entry.

Stale entries can be exploited. A bad actor could spoof a domain associated with an inactive seller_id, knowing the account is no longer monitored but still appears in your sellers.json as verified.

Communicate changes to affected sellers

When you change a publisher's seller_type, update their domain field, or modify their seller_id format, notify them. A simple email gives them a chance to update their ads.txt in sync with your sellers.json change.

Most verification failures happen because changes on one side (SSP or publisher) don't get communicated to the other side.

Common SSP Mistakes

Defaulting all sellers to confidential

Some SSPs default new accounts to confidential status "for privacy." This sounds protective, but it hurts publishers by hiding their identity from DSPs. Unless the publisher explicitly requests confidential status, default to non-confidential.

Not updating after platform migrations

When you migrate to a new ad server, rebrand, or consolidate platforms, seller_id formats often change. If you don't update sellers.json in sync with the migration, every publisher on your platform suddenly has a verification mismatch.

Map old IDs to new IDs during migrations. Update sellers.json before the migration goes live. Notify affected publishers so they can update ads.txt.

Including incomplete data

Some SSPs publish sellers.json files with missing required fields. An entry with seller_id but no domain or seller_type meets the technical spec (those fields can be omitted if is_confidential is true), but it creates a verification gap.

If you're going to list a seller, list them completely. Partial data is often worse than no data because it signals the account exists but provides no verification value.

Slow update cadence

Updating sellers.json monthly or quarterly is too slow for a file that DSPs check on every bid. Publishers add and remove SSPs continuously. Accounts change. Domains rebrand.

If your update cadence is measured in weeks, your file is always partially stale, which means publisher verification is always partially broken.

The Competitive Angle

DSPs are consolidating their supply paths. They're cutting SSPs that don't meet transparency and quality bars. Your sellers.json file is part of how they evaluate you.

Two SSPs, similar inventory, similar scale. One has a clean, daily-updated, 95% non-confidential sellers.json. The other has a monthly-updated file with 60% confidential entries and frequent mismatches. Which one do you think DSPs prioritize?

Treat sellers.json as competitive infrastructure. It's not just compliance. It's how you signal quality to buyers.

BeamFlow's SSP audit tool cross-references your sellers.json against 220K+ publisher ads.txt files, showing you exactly which entries fail verification and how your transparency metrics compare to industry benchmarks.

Frequently Asked Questions

Do all SSPs need a sellers.json file?

The IAB Tech Lab spec says sellers.json is required for all advertising systems that accept bids. In practice, most major SSPs have implemented it, but some smaller SSPs and ad networks haven't. If you're operating a platform that receives bids from DSPs, you need one.

How big do sellers.json files get?

It depends on your seller count. Major SSPs have files with 100,000+ entries and file sizes in the multiple megabytes. Google's sellers.json is over 5 MB. DSPs cache these files, so size isn't usually a performance issue, but you should serve the file with compression (gzip) and use a CDN if your file is large.

What happens if we don't maintain sellers.json?

DSPs can't verify your sellers. Bid requests from your platform fail verification checks. Over time, DSPs may deprioritize or remove your platform from their supply path entirely. Publishers on your platform see lower fill rates and CPMs without understanding why.

Can we mark specific sellers as confidential if they request it?

Yes, but understand the trade-off. Confidential entries reduce verification transparency. Some DSPs exclude confidential sellers entirely. If a publisher requests confidential status, explain the SPO impact. Most publishers don't realize confidentiality hurts their own demand.

Should we include test accounts or internal accounts in sellers.json?

Only if they actively send bid requests to DSPs. If an account is internal-only or used for testing without live traffic, don't list it. Only list accounts that represent real seller relationships with live inventory.

How often should we audit our sellers.json for accuracy?

Continuously. Build automated validation into your seller onboarding and account management workflows. Run weekly audits comparing sellers.json data against your internal CRM and payment systems to catch drift. Any mismatch between what your internal systems say and what sellers.json reports is a verification failure waiting to happen.