What does the supply chain object (schain) show about each bid?
Part of Supply path transparency
The short answer
The supply chain object, or schain, is part of an OpenRTB bid request that lists, in order, every company paid along the way for that impression, from the inventory owner to the system sending the request. Each node gives an advertising system's domain and a seller ID, and a complete flag says whether the chain reaches back to the owner.
Key takeaways
- schain describes one bid request, so it shows the path actually taken, while ads.txt and sellers.json describe the paths that are allowed.
- Each node's asi and sid should match an ads.txt line and a sellers.json entry, which is how live traffic is joined to the public files.
- complete is 1 only when the chain reaches back to the owner of the site, app or other medium; a reseller that receives no chain must start one marked 0.
- A reseller may not pass on an existing chain without adding its own node, and one that will not add a node should send no chain at all.
- Buyers who do not run their own bidder read schain through log fields or request samples from their buying platform.
What is the supply chain object, and where does it sit in a bid request?
The SupplyChain object specification (opens in a new tab) states its purpose plainly: to let buyers see all parties who are selling or reselling a given bid request. It began as an extension usable with OpenRTB 2.5 and was officially added to the Source object in OpenRTB 2.6 and 3.0. Where it sits depends on the protocol version: BidRequest.Source.schain in 2.6 or later, BidRequest.Source.ext.schain in 2.5, and BidRequest.ext.schain in 2.4 or earlier.
Definition
- Supply chain object (schain)
- An object inside an OpenRTB bid request whose ordered nodes name every entity involved in the direct flow of payment for that impression, with a flag that says whether the list reaches back to the inventory's owner.
In OpenRTB 2.6 (opens in a new tab), schain shares the Source object with three other attributes that matter to supply path work. The Source object describes the entity upstream from the exchange, and the specification names header bidding as a common case where the exchange does not make the final decision.
| Attribute | Status | Definition |
|---|---|---|
| fd | Recommended | Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source |
| tid | Recommended | Transaction ID that must be common across all participants in this bid request, potentially multiple exchanges |
| pchain | Recommended | Payment ID chain string, using the syntax of the TAG Payment ID Protocol v1.0 |
| schain | Recommended | The links in the supply chain and an indicator of whether the chain is complete |
What does each node in schain contain?
The object itself has three required attributes: complete, nodes and ver, the version of the supply chain specification in major.minor form, such as 1.0. The nodes array is ordered. In a complete chain the first node is the owner's advertising system and seller ID; in an incomplete chain it is the first known node. The last node is always the entity sending this bid request.
| Attribute | What the specification says | How a buyer uses it |
|---|---|---|
| asi (required) | The canonical domain of the SSP, exchange or header wrapper that bidders connect to; should match the value used in ads.txt | Find the matching ads.txt line and the sellers.json to open |
| sid (required) | The seller or reseller account within that system, the same value used in transactions, limited to 64 characters | Look up the seller_id in that system's sellers.json |
| rid (optional) | The OpenRTB request ID as issued by this seller | Trace one request across the hops in logs |
| name and domain (optional) | The paid legal entity and its business domain; should not be included when they already exist in sellers.json | Expect them to be empty and rely on the sellers.json lookup |
| hp (required) | Whether this node is involved in the flow of payment; for version 1.0 it should always be 1 | A 0 in a version 1.0 chain is a sign the chain was built incorrectly |
How is a supply chain built as a request passes between sellers?
Every system that handles the request is responsible for its own link. The specification's implementation rules are short, and knowing them lets a buyer tell whether a chain was built correctly or simply copied forward.
The specification's rules for building a chain
- Start complete at the source. The originating bid request creates the object with complete set to 1 and the originating system's own node as the only entry.
- Append when reselling. A reseller that receives a chain copies it, keeps the original complete value and adds its node to the end of the nodes array.
- Start incomplete when nothing arrived. A reseller that receives inventory with no chain creates one itself, sets complete to 0 and inserts its own node.
- Never pass a chain through silently. Copying the previous seller's chain without inserting a node is invalid; a reseller that will not insert itself should send no chain.
How do buyers read a supply path from schain?
Reading a chain means joining each node to the public files. The ads.txt 1.1 specification (opens in a new tab) says that in a complete chain, the first node should have a sellers.json domain that matches the site's OWNERDOMAIN, and that for inventory a manager monetizes, the MANAGERDOMAIN is expected to be the domain of that originating node. Buying platforms run related checks: Display & Video 360 help (opens in a new tab) says it checks every seller identified in the chain, intermediaries included, against the publisher's ads.txt or app-ads.txt, and treats an empty SupplyChain object as unauthorized.
| Pattern in the request | What it shows | Reasonable next step |
|---|---|---|
| complete 1, one node | The owner's own system sent the request with no hops | Confirm the node domain matches OWNERDOMAIN; the shortest possible path |
| complete 1, several nodes | The full path is known; the first node is the owner and later nodes resold the request | Check every node is authorized and ask whether a shorter path to the site exists |
| complete 0 | At least one upstream system did not supply a chain; the first node is only the first known party | Treat the owner as unconfirmed for this path |
| A node's sid missing from its sellers.json | The paid party on that hop cannot be identified | Raise it with the exchange that sent the request |
| Empty SupplyChain object | No path information at all | Expect platforms that treat it as unauthorized not to bid |
How does schain travel in video tags and other non OpenRTB requests?
Not every request is OpenRTB. Ad tags in ad servers and video players, and VAST URLs, can carry the chain as a string. The specification recommends a URL parameter named schain and a fixed order: the version and complete flag first, separated by a comma, then each node, with nodes separated by an exclamation mark. Inside a node the order is asi, sid, hp, rid, name, domain and ext, and optional values can be left empty.
What does a schain review look like on a real plan?
Fictional example
A farm equipment dealer in Saskatchewan
A fictional farm equipment dealer with yards across Saskatchewan runs display and online video beside crop, weather and rural news sites. After the first week of a campaign, its agency asks the trading desk for schain fields from a sample of won impressions on the 12 sites in the deal.
A provincial agriculture news site shows complete set to 1 and a single node whose sellers.json domain matches its OWNERDOMAIN. A weather site shows complete set to 1 with two nodes: the owner's exchange, then a second exchange that resold the request. The site is also available directly on the first exchange, so the desk asks the platform to prefer that path.
A rural lifestyle blog's video impressions arrive with complete set to 0 and a first node belonging to a reseller. The desk cannot confirm who owns that inventory from the chain, so it keeps the blog's display path, which is complete, and pauses the video path until the publisher explains how its player is sold.
How does PlacementGraph help before any schain data exists?
What can the supply chain object not tell a buyer?
Version 1.0 covers only the entities involved in the direct flow of payment; the specification says future versions may add parties that take part without being paid. A chain carries no fees or prices, and one request's chain says nothing about the other paths the same impression may have taken at the same moment. Each node is written by the system that adds it, so the chain is only as accurate as the systems that build it, which is why buyers join it to ads.txt and sellers.json rather than reading it alone.
Questions to ask the trading desk about schain
- Is schain logged for won impressions as well as for bids?
- Are node seller IDs joined to sellers.json names in the reports we receive?
- Are requests with complete set to 0 excluded, or only reported?
- Does any site in the deal reach us through more than one first node?
- Are video and CTV requests carrying a chain, including serialized chains in VAST URLs?
Frequently asked questions
Why would a supply chain be marked incomplete?
One cause is an upstream system that did not send one. The specification's own example shows an originating request from a system that does not support the object; the reseller that receives it must create a new chain, mark complete as 0 and add itself, so the owner's node is missing.
Is an incomplete chain a reason to stop buying a site?
Not automatically. It means that path cannot be traced back to the owner on that request. A buying team can set a policy for complete 0 traffic and look for another path to the same site that arrives complete. Treat the decision as a rule the team writes down, applied the same way to every site.
What is the tid field that sits next to schain?
tid is the transaction ID in the OpenRTB 2.6 Source object. The specification says it must be common across all participants in the bid request, potentially multiple exchanges, which is meant to let systems recognize one impression opportunity as it passes between them.
Does schain work for mobile apps and connected TV?
Yes. The object sits in the bid request whatever the medium, and the specification's own examples use app requests. For tag based video and CTV buys, the chain can travel as a serialized string in a VAST URL. Authorization for apps is then checked against app-ads.txt instead of ads.txt.
Which version of the supply chain object is in use?
Version 1.0. The ver attribute carries it as the string 1.0, and the specification says the hp flag should always be 1 in this version. OpenRTB 2.6 lists SupplyChain and SupplyChainNode as standard objects, with schain recommended on the Source object.
Sources
- OpenRTB SupplyChain object (opens in a new tab)IAB Tech Lab, OpenRTB repository
- OpenRTB 2.6 specification (opens in a new tab)IAB Tech Lab, OpenRTB 2.x repository
- ads.txt Specification Version 1.1 (opens in a new tab)IAB Tech Lab, Supply Chain Validation repository
- Sellers.json and the OpenRTB SupplyChain object (opens in a new tab)IAB Tech Lab
- Authorized Digital Sellers (opens in a new tab)Google, Display & Video 360 Help
Researched and written by PlacementGraph Research. Read how we research, source and update these pages. Corrections: diana@placementgraph.com.