> [!WARNING] > This feature is in beta. Contact your account manager if you are interested in testing this feature. ## Overview You can use win and loss notifications to receive pings with details about wins and losses for your bids. You can configure these notifications to include server-side auction feedback similar to [Real-time feedback](https://developers.google.com/authorized-buyers/rtb/request-guide#real-time-feedback), as well as mediation chain feedback. You can configure notifications by populating corresponding fields with a URL in the bid response. Google will ping the win notification URL if the bid wins, or the loss URL if the bid is filtered or lost. We recommend that you construct win and loss notification URLs to include request-level data; for example, the bid request ID, and use [macros](https://developers.google.com/authorized-buyers/rtb/response-guide/win-and-loss-notifications#supported-macros) to get your preferred data. These URLs are specified in the following response fields: - Win notification URL: `BidResponse.seatbid.bid.nurl` - Loss notification URL: `BidResponse.seatbid.bid.lurl` > [!NOTE] > **Note:** There may be duplicate win loss notifications sent for a small percentage of bids. The bidder is responsible for de-duplicating these notifications. ### Mobile app mediation chains Mobile app publishers often use a mediation chain in products such as [Ad Manager](https://support.google.com/admanager/answer/6272813?sjid=7253782529960967-NA) and [AdMob](https://support.google.com/admob/answer/13420272?sjid=7253782529960967-NA) to have their ad request reach multiple ad networks, increasing the likelihood of their inventory being filled. Mediation uses a waterfall model where ad networks are ordered by their expected bid in descending value, and the first network in the waterfall to return a winning bid will place their ad. As a result, it is possible for you to place a winning bid for mobile inventory in Google's exchange, and still not win the impression in the overall mediation chain. Win and loss notifications can help you understand your bid's status in the overall mediation chain. If the mediation chain result is known to Google, then the notification that is sent reflects whether your bid won or lost in the mediation chain. Moreover, if your bid loses in the mediation chain, Google communicates the winning mediation chain element's estimated CPM in the loss notification. Together with the server-side minimum bid to win, you can determine the overall bid you had to submit in order to win the impression by taking the maximum of the two values. > [!NOTE] > **Note:** Due to technical limitations, Google may rarely send notifications that don't include the mediation chain result. > [!CAUTION] > **Caution:** Bids containing notification URLs exceeding 3000 characters in length won't receive notifications that include the mediation chain result. ## Supported macros Macros can help provide insight into both the server-side auction and the on-device mediation waterfall. Macros supported in win and loss notification URLs include the following. | **Macro string** | **Description** | **Supported in `nurl`** | **Supported in `lurl`** | |---|---|---|---| | `${AUCTION_ID}` | The ID of the bid request. | Yes | Yes | | `${AUCTION_BID_ID}` | The ID of the bid in the bid response. | Yes | Yes | | `${AUCTION_IMP_ID}` | The ID of the impression in the bid response. | Yes | Yes | | `${AUCTION_SEAT_ID}` | The ID of the bidder seat in the bid response. | Yes | Yes | | `${AUCTION_AD_ID}` | The ID of the ad in the bid response. | Yes | Yes | | `${AUCTION_PRICE}` | The impression cost in **CPM** in units of the bid currency if the bid won the auction. This is different from the use of the macro in impression tracking URLs, where the same macro is replaced with an **encoded** impression cost in **CPI micros** and units of the bid currency. | Yes | No | | `${AUCTION_LOSS}` | Google supports most OpenRTB [loss reason codes](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/master/OpenRTB%20v3.0%20FINAL.md#list--loss-reason-codes-). Additionally, Google will send loss reason value `501` to indicate that a bid lost in the mediation waterfall. | Yes | Yes | | `${CREATIVE_STATUS_CODE}` | Google-specific status code for the ad. Possible values can be found in [creative-status-codes.txt](https://storage.googleapis.com/adx-rtb-dictionaries/creative-status-codes.txt). | Yes | Yes | | `${AUCTION_MIN_TO_WIN}` | The minimum bid to win of the server side auction in CPM and units of the bid currency. If this macro is replaced by a non-empty string, the bid had to have been higher than the replaced macro value in order to win the server side auction. The units are different from the existing `BidRequest.ext.bid_feedback.minimum_bid_to_win` field, which is expressed in CPM and units of the buyer account currency. | Yes | Yes | | `${WINNING_MEDIATION_ECPM}` | The estimated CPM of the winning item in the mediation chain in units of the bid currency. This macro is replaced with an empty string if there is no estimated CPM associated with the line item or if the estimated CPM is unavailable. If this macro is replaced by a non-empty string, the bid had to have been higher than the replaced macro value in order to win the mediation waterfall. | No | Yes | ## Example Bid Responses ### OpenRTB Protobuf ```protobuf ... seatbid { ... bid { ... nurl: "http://example.com/win?win_price=${AUCTION_PRICE}&mbtw=${AUCTION_MIN_TO_WIN}" lurl: "http://example.com/loss?mbtw=${AUCTION_MIN_TO_WIN}&loss_reason=${AUCTION_LOSS}&creative_status_code=${CREATIVE_STATUS_CODE}&mediation_ecpm=${WINNING_MEDIATION_ECPM}" } } ``` ### OpenRTB JSON ```json { ... "seatbid": [ ... "bid": [ { ... "nurl": "http://example.com/win?win_price=${AUCTION_PRICE}&mbtw=${AUCTION_MIN_TO_WIN}", "lurl": "http://example.com/loss?mbtw=${AUCTION_MIN_TO_WIN}&loss_reason=${AUCTION_LOSS}&creative_status_code=${CREATIVE_STATUS_CODE}&mediation_ecpm=${WINNING_MEDIATION_ECPM}" } ] ] } ```