Bidder Billing Report API Service
Buyers can gather transaction information using the Bidder Billing Report to invoice their advertisers.
For instructions on retrieving a report, please see Report Service.
report_interval field in the JSON request can be set to one of the following:
The hour of the impression. Note: For impressions older than 100 days, hourly data is aggregated into one row with 'YYYY-MM-DD 00:00:00' as the hour ('YYYY-MM-DD' is the UTC day in which the activity happened). This will make it look as though all activity happened at midnight. All daily data older than 100 days is returned in the UTC time zone.
The day of the impression.
The month of the impression.
Internal ID of the buyer member.
Display name of the buyer member.
Internal ID of the seller member.
Display name of the seller member.
Internal ID of the publisher.
|geo_country||string||Yes||Yes||"US"||The code for the geographic country.|
|geo_country_name||string||No||No||"United States"||The name of the geographic country.|
|deal_id||int||Yes||Yes||123||The internal ID of the deal.|
|deal_name||string||No||No||"Deal A"||The display name of the deal.|
Whether or not the buyer pays the seller directly for the cost of media. If 0, Xandr collects the cost of media from the buyer and pays the seller. If 1, the buyer pays the seller directly for the cost of media. Tip: Buyers can match the cost of media on their invoice by filtering out "cleared direct" transactions.
The transaction currency used by the buyer to purchase this impression.
|selling_currency||string||Yes||Yes||"EUR"||The transaction currency used by the seller to sell this impression.|
The ID for the type of impression. Possible values (associated types in parentheses):
|imps||int||100||imps_delivered||The total number of impressions served successfully.|
|imps_direct_cleared||int||100||imps_direct_cleared||The total number of impressions where Xandr does NOT collect buyer media cost or pay out seller payment for transactions between this buyer-seller pair.|
|imps_appnexus_cleared||int||100||imps_appnexus_cleared||The total number of impressions where Xandr collects buyer media cost and pays out seller payments for transactions between this buyer-seller pair.|
|buyer_media_cost||money||123.45||buyer_media_cost||The total cost of the inventory purchased.|
|buyer_media_cost_direct_cleared||money||123.45||buyer_media_cost on imps_direct_cleared||The buyer's spend for impressions where the seller payment is transacted directly between this buyer-seller pair, not through Xandr.|
|buyer_media_cost_direct_cleared_buying_currency||money||123.45||buyer_media_cost_direct_cleared_buying_currency||The buyer's spend for impressions where the seller payment is transacted directly between this buyer-seller pair, not through Xandr, in the transaction currency the buyer used to buy the impression.|
|buyer_media_cost_appnexus_cleared||money||123.45||buyer_media_cost on imps_appnexus_cleared||The buyer's spend for impressions where Xandr pays out the seller payment.|
|buyer_media_cost_direct_cleared_buying_currency||money||123.45||buyer_media_cost_direct_cleared_buying_currency||The buyer's spend for impressions where Xandr pays out the seller payment, in the transaction currency the buyer used to buy the impression.|
|buyer_media_cost_buying_currency||money||123.45||buyer_media_cost_buying_currency||The total cost of the inventory purchased, in the transaction currency the buyer used to buy the impression.|
Total fees charged for hosted creatives that exceed the creative size limit.
|creative_overage_fees_buying_currency||money||123.45||creative_overage_fees_buying_currency||Total fees charged for hosted creatives that exceed the creative size limit, in the transaction currency the buyer used to buy the impression.|
The fee charged on RTB bought impressions specified in the buyer member's contract. For example, with a 10% fee, if the buyer spends $1,000 on inventory, Xandr charges them a $100 fee. They will receive an invoice for $1,000 of Media Cost and $100 for Buyer Auction Service Charge (BASC) for a total of $1,100.
There are two types:
|auction_service_fees_buying_currency||money||123.45||auction_service_fees_buying_currency||The fee charged on RTB bought impressions specified in the buyer member's contract, in the transaction currency the buyer used to buy the impression.|
The deduction on RTB bought impressions specified in the buyer member's contract. For example, with a 10% deduction, if they budget $1,000 for their campaign, Xandr takes $100 from that, leaving the buyer with $900 that is used to purchase inventory from the seller. Creative Auction Service Change (CASC) will also be represented here. For the example above, the buyer will receive an invoice for $1,000 of Media Cost, which is inclusive of the deduction Xandr charges.
This field matches auction_service_fees if your contract has a Buyer Auction Service Charge (BASC) rate of greater than 0%.
|auction_service_deduction_buying_currency||money||123.45||auction_service_deduction_buying_currency||The deduction on RTB bought impressions specified in the buyer member's contract, in the transaction currency the buyer used to buy the impression.|
|money||123.45||buyer_media_cost / imps_delivered * 1000||The buyer's cost per impression, expressed in eCPM.|
|buyer_ecpm_buying_currency||money||123.45||buyer_ecpm, expressed in the buyer's currency||The buyer's cost per impression in their selected currency. For a list of supported currencies, see Supported Currencies.|
1. Create the JSON-formatted report request
The JSON file should include the
report_type "bidder_pricing_report", as well as the
columns (dimensions and metrics) and
report_interval that you want to retrieve. You can also filters for specific dimensions, define granularity (year, month, day), and specify the format in which the data should be returned (csv, excel, or html). For a full explanation of fields that can be included in the JSON file, see the Report Service.
2. POST the request to the Reporting Service
3. GET the report status from the Report Service
Make a GET call with the Report ID to retrieve the status of the report. Continue making this GET call until the
execution_status is "ready". Then use the report-download service to save the report data to a file, as described in the next step.
4. GET the report data from the Report Download Service
To download the report data to a file, make another GET call with the Report ID, but this time to the report-download service. You can find the service and Report ID in the
url field of the previous GET response. When identifying the file that you want to save to, be sure to use the file extension of the "format" that you specified in your initial POST.
If an error occurs during download, the response header will include an HTTP error code and message. Use -i or -v in your call to expose the response header.