Stay organized with collections
Save and categorize content based on your preferences.
Overview
You can use win and loss notifications to receive pings with details about wins and losses
for your bids in Real-time Bidding. These are only supported when bidding on mobile app
inventory. You can configure these notifications to include server-side auction feedback
similar to Real-time feedback,
as well as mediation chain feedback.
Mobile app publishers use a mediation chain in products such as
Ad Manager
and AdMob
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.
Google recommends that you implement win and loss notifications for mobile app inventory in
order to be better informed of your win or loss in the mediation chain. These are configured
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 to get your
preferred data. These URLs are specified in the following response fields:
Win URL: BidResponse.seatbid.bid.nurl
Loss URL: BidResponse.seatbid.bid.lurl
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.
OpenRTB
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.
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.
[null,null,["Last updated 2025-08-18 UTC."],[[["\u003cp\u003eWin and loss notifications provide real-time updates on bid outcomes for mobile app inventory, allowing for informed bidding strategy adjustments.\u003c/p\u003e\n"],["\u003cp\u003eMediation chains, utilized by mobile app publishers, mean that winning a bid in the Google exchange does not guarantee winning the impression in the overall mediation process.\u003c/p\u003e\n"],["\u003cp\u003eImplementing win and loss notifications, configured through specific URLs in the bid response, allows bidders to understand if they won or lost in the mediation chain.\u003c/p\u003e\n"],["\u003cp\u003eMacros are available for use in win and loss notification URLs to provide detailed insights into the server-side auction and the on-device mediation waterfall, such as the auction ID, bid price, and loss reasons.\u003c/p\u003e\n"],["\u003cp\u003eOpenRTB and Google RTB have their respective fields (\u003ccode\u003enurl\u003c/code\u003e/\u003ccode\u003elurl\u003c/code\u003e and \u003ccode\u003ewin_notice_url\u003c/code\u003e/\u003ccode\u003eloss_notice_url\u003c/code\u003e) for specifying win and loss notification URLs, which can include various supported macros.\u003c/p\u003e\n"]]],[],null,["# Win and loss notifications\n\n| This feature is in beta. Contact your account manager if you are interested in testing this feature.\n\nOverview\n--------\n\nYou can use win and loss notifications to receive pings with details about wins and losses\nfor your bids in Real-time Bidding. These are only supported when bidding on mobile app\ninventory. You can configure these notifications to include server-side auction feedback\nsimilar to [Real-time feedback](/authorized-buyers/rtb/request-guide#real-time-feedback),\nas well as mediation chain feedback.\n\nMobile app publishers use a mediation chain in products such as\n[Ad Manager](//support.google.com/admanager/answer/6272813?sjid=7253782529960967-NA)\nand [AdMob](//support.google.com/admob/answer/13420272?sjid=7253782529960967-NA)\nto have their ad request reach multiple ad networks, increasing the likelihood of their\ninventory being filled. Mediation uses a waterfall model where ad networks are ordered by\ntheir expected bid in descending value, and the first network in the waterfall to return a\nwinning bid will place their ad. As a result, it is possible for you to place a winning bid\nfor mobile inventory in Google's exchange, and still not win the impression in the overall\nmediation chain.\n\nGoogle recommends that you implement win and loss notifications for mobile app inventory in\norder to be better informed of your win or loss in the mediation chain. These are configured\nby populating corresponding fields with a URL in the bid response. Google will ping the win\nnotification URL if the bid wins, or the loss URL if the bid is filtered or lost. We\nrecommend that you construct win and loss notification URLs to include request-level data;\nfor example, the bid request ID, and use [macros](#supported-macros) to get your\npreferred data. These URLs are specified in the following response fields:\n\n- Win URL: `BidResponse.seatbid.bid.nurl`\n- Loss URL: `BidResponse.seatbid.bid.lurl`\n\n| **Note:** Due to technical limitations, Google may rarely send notifications that don't include the mediation chain result.\n| **Caution:** Bids containing notification URLs exceeding 3000 characters in length may be subject to filtering.\n\nSupported macros\n----------------\n\nMacros can help provide insight into both the server-side auction and the on-device\nmediation waterfall. Macros supported in win and loss notification URLs include the\nfollowing.\n\n#### OpenRTB\n\n| **Macro string** | **Description** | **Supported in `nurl`** | **Supported in `lurl`** |\n|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-------------------------|\n| `${AUCTION_ID}` | The ID of the bid request. | Yes | Yes |\n| `${AUCTION_BID_ID}` | The ID of the bid in the bid response. | Yes | Yes |\n| `${AUCTION_IMP_ID}` | The ID of the impression in the bid response. | Yes | Yes |\n| `${AUCTION_SEAT_ID}` | The ID of the bidder seat in the bid response. | Yes | Yes |\n| `${AUCTION_AD_ID}` | The ID of the ad in the bid response. | Yes | Yes |\n| `${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 |\n| `${AUCTION_LOSS}` | Google supports most OpenRTB [loss reason codes](//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. | No | Yes |\n| `${CREATIVE_STATUS_CODE}` | Google-specific status code for the ad. Possible values can be found in [creative-status-codes.txt](//storage.googleapis.com/adx-rtb-dictionaries/creative-status-codes.txt). | No | Yes |\n| `${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 |\n| `${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 |\n\nExample Bid Responses\n---------------------\n\n### OpenRTB Protobuf\n\n```protobuf\n...\nseatbid {\n ...\n bid {\n ...\n nurl: \"http://example.com/win?win_price=${AUCTION_PRICE}&mbtw=${AUCTION_MIN_TO_WIN}\"\n 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}\"\n }\n}\n \n```\n\n### OpenRTB JSON\n\n```json\n{\n ...\n \"seatbid\": [\n ...\n \"bid\": [\n {\n ...\n \"nurl\": \"http://example.com/win?win_price=${AUCTION_PRICE}&mbtw=${AUCTION_MIN_TO_WIN}\",\n \"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}\"\n }\n ]\n ]\n}\n \n```"]]
