Buyer Pricing Rules

A bid request can contain multiple pricing rules in the MatchingAdData.pricing_rule repeated field. This means that a particular AdSlot could have different min_cpm for a given group of advertisers and agencies. To avoid filtering for a bid that is too low, buyers need to check the BuyerPricingRule message in the bidRequest.

It's possible for a buyer pricing rule to get truncated due to a size limit. If this happens, no buyer pricing rules are sent.

Minimum bid CPM

There are two places where the minimum bid CPM price can be located:

  1. General - This would be the default minimum price to bid if there are no pricing rules.

  2. Publisher rules - Publishers can set price rules for specific buyers, agencies or advertisers.



  • Advertisers/agencies can be included or excluded

    • If included, the BuyerPricingRule.blocked flag (if set to true) or BuyerPricingRule.minimum_cpm_micros applies to them.
    • If excluded, the pricing rule will apply for all other advertisers/agencies.
  • BuyerPricingRule.blocked and BuyerPricingRule.minimum_cpm_micros cannot be set at the same time in a pricing_rule. Only one can be set at a time.

  • The rules are listed in priority order; if there is more than one matching rule for a specific bid, the first one applies.

  • The last rule will always be a catch-all rule (included_advertisers, excluded_advertisers, included_agencies, excluded_agencies are all empty), and its minimum_cpm_micros field should be equal to MatchingAdData.minimum_cpm_micros, but not always.

  • It is important to read the BuyerPricingRule.blocked flag. If it is set to true in the first pricing rule matching the bid, the bid will get filtered regardless of the bid amount. Filtering will be for either ADX_AD_FILTERED_BY_RULE_EXCLUSION or BELOWCPM.

  • Publishers can set their inventory to be branded or anonymous. Buyers can configure their bidder to accept both kinds of requests, and block anonymous if desired. Publishers must block buyers across all branding types in order to trigger an ADX_AD_FILTERED_BY_RULE_EXCLUSION filtering type. If they only block buyers for one branding type, buyer bids will be filtered for BELOWCPM regardless of whether they were blocked or had a min­CPM for the branding type that they used for targeting.

  • There is also a case where bids will be filtered for BELOWCPM when the bid is below the third-party reserve price set by dynamic allocation (but it's not always disclosed in the BidRequest so the buyer won't be able to know).

In short, the best way to bid successfully using the MatchingAdData message is in a situation where more than one of your advertisers applies to a given Bid Request. It will ensure that you select an advertiser that is allowed to bid (either explicitly allowed, or not on the disallowed list). Ignoring the message means that you may occasionally bid with an ad that will just be filtered by publisher blocks and lost, while listening to the message could have given you the opportunity to bid with a valid ad (for a different advertiser) instead.

The actual usefulness will depend on how often publisher rules apply to the advertisers that you have ads for.

Protocol buffer

message MatchingAdData {
  // The adgroup id of the matching ad.
  optional int64 adgroup_id = 2;

  // The minimum CPM value that you can bid to not be filtered before the
  // auction.  This may be a global minimum, or it may be a minimum set by
  // the publisher.  The value is in micros of your account currency.
  optional int64 minimum_cpm_micros = 5;

  // Publisher open auction pricing rules applicable to a particular buyer.
  message BuyerPricingRule {
    // Only one of the included_advertisers and excluded_advertisers fields
    // can be set in a rule.  See advertisers.txt file in the technical
    // documentation for a list of ids.
    repeated int64 included_advertisers = 1;
    repeated int64 excluded_advertisers = 2;

    // Only one of the included_agencies and excluded_agencies fields
    // can be set in a rule.  See agencies.txt file in the technical
    // documentation for a list of ids.
    repeated int64 included_agencies = 3;
    repeated int64 excluded_agencies = 4;

    // Only one of the blocked and minimum_cpm_micros can be set in a rule.
    // If set to true, indicates that the specified advertisers/agencies are

    // blocked from bidding.
    optional bool blocked = 5;

    // Minimum CPM value that you can bid to not be filtered before the
    // auction.  The value is in micros of the bidder account currency.
    optional int64 minimum_cpm_micros = 6;

  // Publisher open auction pricing rules in priority order, from highest to
  // lowest.
  repeated BuyerPricingRule pricing_rule = 7;

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol