Table of Contents






Overview

Sellers.json and SupplyChain Object (schain) are industry specifications, developed by the IAB Tech Lab, to increase supply chain transparency on inventory.

Sellers.json

SSPs and exchanges host sellers.json files, which list all direct sellers and intermediaries that are authorized to sell inventory on their platform. Sellers.json files are used to verify the identity and legitimacy of a seller or reseller, as well as provide additional information to the advertiser, including:​

  • Seller ID - this should match the Publisher ID listed on the publisher’s ads.txt or app-ads.txt file​
  • Seller Name​
  • Website Domain​
  • Seller Type - Publisher, Intermediary, or Both

SupplyChain Object (schain)

The OpenRTB SupplyChain object, also known as schain, shows every entity involved in selling and reselling a bid request. Schain assigns a node to every entity that a payment travels through for a single impression. Advertisers can then view the entire transaction path for each bid request from the original media owner to the final buyer and verify each entity in the chain.


Reporting with sellers.json

Sellers.json dimensions are available in these reporting tools:

  • App, Domain, and Inventory Reports
  • Metamarkets
  • Auction, bid, win, ghost, antenna, and streaming joined win logs

The available sellers.json reporting fields are as follows:

DimensionLogs Field NameDefinition

Sellers.json Seller Status

SELLERS_JSON_STATUS

Whether a match was found when looking up the Publisher ID in sellers.json files. Values include:

  • Unknown: No Publisher ID was passed in the bid request to lookup against sellers.json
  • Seller Not Found: No match was found to the Publisher ID passed in the bid request 
  • Authorized: This seller is authorized based on the sellers.json table, but the seller type cannot be identified for various reasons.  
  • Authorized - Publisher: A match was found to the Publisher ID and the Seller Type is "Publisher"
  • Authorized - Intermediary: A match was found to the Publisher ID and the Seller Type is "Intermediary"
  • Authorized - Both: A match was found to the Publisher ID and the Seller Type is "Both"

Sellers.json Seller Name

SELLERS_JSON_SELLER_NAME

Seller Name listed on the sellers.json file

Mapped Seller Name

SELLERS_JSON_MAPPED_NAME

The Seller Name listed in the in the sellers.json file mapped to a taxonomy to consolidate into a single standardized name

The taxonomy does not account for all sellers names. The most commonly passed seller names have been prioritized. It's recommended to use both the Seller Name and Mapped Seller Name dimensions.

Sellers.json Seller Type

SELLERS_JSON_SELLER_TYPE

The value pulled from the sellers.json file. Options include:

  • Publisher: The inventory sold through this account is owned by the named entity and the advertising system pays them directly.
  • Intermediary: The inventory sold through this account is not owned by the named entity, or the advertising systems does not pay them directly.
  • Both: Both publisher and intermediary inventory are transacted by this account.


SupplyChain Object (schain) Fields in Win Logs

Schain fields are available in the following logs:

  • Auction logs
  • Bid logs
  • Win logs
  • Ghost logs
  • Antenna logs
  • Streaming joined win logs

Below is a list of the available fields and their definitions. The IAB's specs on the SupplyChain Object can also be found in the OpenRTB GitHub.

Logs Field NameDefinition

SCHAIN_COMPLETE

Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory.

SCHAIN_NODE_ASI*

The canonical domain name of the SSP, Exchange, Header Wrapper, etc. system that bidders connect to. This should be the same value as used to identify sellers in an ads.txt file if one exists.

SCHAIN_NODE_DOMAIN*

Business domain name of the entity represented by this node. This value is optional and is not included if it exists in the advertising system’s sellers.json file.

SCHAIN_NODE_HP*

Indicates whether this node will be involved in the flow of payment for the inventory.

SCHAIN_NODE_NAME*

Name of the company (the legal entity) that is paid for inventory transacted under the given seller_id.

SCHAIN_NODE_RID*

OpenRTB RequestId of the request as issued by this seller.

SCHAIN_NODE_SID*

Identifier associated with the seller or reseller account within the advertising system. For example, 1234.

SCHAIN_NODE_INTERNAL_SID*

The SCHAIN_NODE_SID field augmented to include the exchange handle. For example, stv/1234.

SCHAIN_VERSION

Version of the supply chain specification in use.

*This field represents values across all nodes in the object in the form of a comma separated varchar array. The index of each value corresponds to the index of each node on the schain object.


Sellers.json Use Cases in Report Builder and Metamarkets

Below are examples outlining how sellers.json data can drive value. 

Resolve Missing Bid Request Values

Better understanding campaign delivery when values, like Publisher Name or App/Site Name, are missing from the bid request.

  1. Open the Domain, Inventory, or App Report.

  2. Select the following dimensions:

    • Campaign or Line Item identifier (such as Name or ID)

    • Publisher Name

    • json Seller Name

    • Mapped Seller Name

  3. Select a measure (such as Spend or Impressions).

  4. Filter for missing Publisher Name.

 

Verify Bid Request Values

Trust that information passed on the bid request, specifically self-declared fields like Publisher Name and App/Site Name, is true. Compare the values passed with sellers.json data to see if they align and verify seller information.

  1. Open the Domain, Inventory, or App Report.

  2. Select the following dimensions:

    • Campaign or Line Item identifier (such as Name or ID)

    • Publisher Name

    • json Seller Name

    • Mapped Seller Name

  3. Select a measure (such as Spend or Impressions).

  4. Add a filter for Seller Status with the following options selected: "Authorized - Publisher", "Authorized – Intermediary", "Authorized – Both".

Uncover Direct Inventory Paths

Increase efficiency by discovering direct paths to publisher inventory.

  1. Open the Metamarkets Auctions dashboard.

  2. Select the publisher you’re interested in buying under Mapped Seller Name.

  3. Select "Publisher" under Seller Type.

  4. View all inventory sources selling that publisher’s inventory directly.

 

Gain Visibility Into All Available Inventory 

Discover inventory sources selling a publisher’s inventory when bid request values are missing. 

  1. Open the Metamarkets Auctions dashboard.

  2. Select the publisher you’re interested in buying under Mapped Seller Name.

  3. Select the Authorized Seller Statuses (Publisher, Intermediary, Both).

  4. Select "Not Available" under Publisher Name and App/Site Name.

  5. View all inventory sources selling that publisher’s inventory that are not passing the values on the bid request.