Partilhar via


Digital Platform API - Buying Billing report

Warning

This report should only be used for data after September 30, 2015.

The Buying Billing Report can be used to view billing data across direct advertiser impressions (bought across direct publishers and real-time inventory).

For instructions on retrieving a report, see Report Service.

Time frame

The report_interval field in the JSON request can be set to one of the following:

  • last_hour
  • today
  • yesterday
  • last_48_hours
  • last_7_days
  • last_30_days
  • month_to_date
  • quarter_to_date
  • last_month
  • lifetime
  • custom

Data retention period

Data retention period for this report is 1095 days.

Note

To run a report for a custom time frame, set the start_date and end_date fields in your report request. For more details about these fields, see Report Service.

Dimensions

Column Type Filter? Example Description
hour time No "2010-02-01 06:00:00" 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.
day time No "2010-02-01" The day of the impression.
month time No "2010-02" The month of the impression.
buyer_member_id int Yes 123 Internal ID of the buyer member.
buyer_member_name string No "My Network" Display name of the buyer member.
seller_member_id int Yes 456 Internal ID of the seller member.
seller_member_name string No "That Seller" Display name of the seller member.
advertiser_id int Yes 789 Internal ID of the advertiser.
advertiser_name string No "Verizon" Display name of the advertiser.
advertiser_code string No "Advertiser Code" The external code associated with an advertiser.
insertion_order_id int Yes 451 Internal ID of the insertion order.
insertion_order_name string No "Q1-2014" Display name for the insertion order.
insertion_order_code string No "Insertion Order Code" The external code associated with an insertion order.
line_item_id int Yes 932 Internal ID of the line item.
line_item_name string No "$3 CPM Verizon Remarketing" Display name of the line item.
line_item_code string No "Line Item Code" The external code associated with a line item.
campaign_id int Yes 728 Internal ID of the campaign.
campaign_name string No "Test" Display name of the campaign.
campaign_code string No "Campaign Code" The external code associated with a campaign.
publisher_id int Yes 321 Internal ID of the publisher.
publisher_name string No "Test" Display name of the publisher.
deal_id int Yes 123 The internal id of the deal.
deal_name string No "Deal A" The display name of the deal.
buying_currency string Yes "USD" The transaction currency used by the buyer to purchase this impression.
selling_currency string Yes "EUR" The transaction currency used by the seller to sell this impression.
imp_type_id int Yes 1 The ID for the type of impression. Possible values (associated types in parentheses):
- 1 ("Blank"): No creative served.
- 2 ("PSA"): A public service announcement served because there were no valid bids and no default creative was available.
- 3 ("Default Error"): A default creative served due to a timeout issue.
- 4 ("Default"): A default creative served because there were no valid bids.
- 5 ("Kept"): Your advertiser's creative served on your publisher's site.
- 6 ("Resold"): Your publisher's impression was sold to a third-party buyer.
- 7 ("RTB"): Your advertiser's creative served on third-party inventory.
- 8 ("PSA Error"): A public service announcement served due to a timeout issue or lack of a default creative.
- 9 ("External Impression"): An impression from an impression tracker.
- 10 ("External Click"): A click from a click tracker.
imp_type string Yes "Blank" The type of impression. For possible values, see imp_type_id.
cleared_direct int Yes 0, 1 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.
marketplace_clearing_event string Yes "Views - Standard Display" The name of the underlying auction event that was transacted (e.g., impression, viewable impression, completed video). For more information, see Guaranteed Outcomes and Supported Viewability Standards in the UI documentation.
split_id int yes 342 The ID of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_id (if included) will be null.
split_name string yes "Mobile Split A" The name of the split that purchased the impressions in this data set. Splits are only applicable to augmented line items. For any reports that contain campaigns, the split_name (if included) will be null.

Metrics

Column Type Example Formula Description
imps int 123456 imps Total number of impressions.
clicks int 123456 clicks Total number of clicks across all impressions.
convs int 123456 total_convs Total number of conversions across all impressions.
booked_revenue money 123.45 booked_revenue Network revenue booked through direct advertisers.
booked_revenue_dollars_buying_currency money 123.45 booked_revenue_dollars_buying_currency Network revenue booked through direct advertisers, in the transaction currency the buyer used to buy the impression.
buyer_media_cost money 123.45 buyer_media_cost The total cost of the inventory purchased.
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.
auction_service_deduction money 123.45 auction_service_deduction The total deductions charged for impressions bought from third parties.
These deductions are included in the buyer's media cost and deducted when calculating the seller's payment. For more information, see Buyer Auction Service Charge Mechanics.
auction_service_deduction_buying_currency money 123.45 auction_service_deduction_buying_currency The total deductions charged for impressions bought from third parties, in the transaction currency the buyer used to buy the impression.
These deductions are included in the buyer's media cost and deducted when calculating the seller's payment. For more information, see Buyer Auction Service Charge Mechanics.
net_media_cost money 123.45 net_media_cost The total amount to be paid for media purchases, less the Auction Service Deduction.
net_media_cost_buying_currency money 123.45 net_media_cost_buying_currency The total amount to be paid for media purchases, less the Auction Service Deduction, in the transaction currency the buyer used to buy the impression.
creative_overage_fees money 123.45 creative_overage_fees 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.
auction_service_fees money 123.45 auction_service_fees Total fees charged for impressions bought from third parties.
These fees are charged in addition to the buyer's media cost. For more information, see Buyer Auction Service Charge Mechanics.
auction_service_fees_buying_currency money 123.45 auction_service_fees_buying_currency Total fees charged for impressions bought from third parties, in the transaction currency the buyer used to buy the impression.
These fees are charged in addition to the buyer's media cost. For more information, see Buyer Auction Service Charge Mechanics.
marketplace_clearing_event_units int 23 marketplace_clearing_event_units The total number of events purchased (for the associated Clearing Event). When buying a Clearing Event other than impression (e.g., viewable impressions), the number of billed events will be less than the number of impressions. For more information, see Guaranteed Outcomes in the UI documentation.
exchange_cost money 4.32 exchange_cost The amount taken out of the exchange to give to the seller. If you aren't using a line item with a guaranteed outcomes payment model, this metric's value equals Net Media Cost.
ecpm_conversion_deduction money 3.2 ecpm_conversion_deduction The amount that Xandr takes out of a guaranteed outcomes bid/payment to cover eCPM conversion and post-auction outcome prediction services. If you aren't using a line item with a guaranteed outcomes payment model, this field's value equals 0.
For more information on how this fee is calculated, see Understanding Payment Conversion Rates.
go_market_making_fee money 0.48 go_market_making_fee The percentage-based fee that Xandr takes out of a guaranteed outcomes bid/payment to cover the risk incurred when providing guaranteed outcomes. This field's value equals 0 when not using a guaranteed outcomes line item. If you aren't using a line item with a guaranteed outcomes payment model, this field's value equals 0.
The target for this fee is 10%, but the actual percentage used varies based on continuously shifting prediction accuracy:
GO Market Making Fee Percentage = Fixed Percentage (10%) ± Prediction Variability (a positive or negative percentage that changes based on shifting prediction accuracy)

For more information on how this fee is calculated, see Understanding Payment Conversion Rates.

Examples

Create the JSON-formatted report request

The JSON file should include the report_type "buyer_invoice_report", as well as the columns (dimensions and metrics) and report_interval that you want to retrieve. You can also filter 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.

$ cat buyer_invoice_report.json

{
    "report": {
        "format": "csv",
        "report_interval": "last_48_hours",
        "columns": [
            "seller_member_name",
            "buyer_member_name",
            "imps",
            "clicks",
            "convs"
        ],
        "report_type": "buyer_invoice_report"
    }
}

POST the request to the Reporting Service specifying a member ID by replacing INSERT_DESIRED_MEMBER_ID

$ curl -b cookies -c cookies -X POST -d @buyer_invoice_report.json 'https://api.appnexus.com/report?member_id=INSERT_DESIRED_MEMBER_ID'

{
 "response": {
   "status": "OK",
   "report_id": "39c4855a07e92433947886b5aabd267d", <=== COPY THIS report_id as you will need it to check the status of your report and to download your report
   "existing": false,
   "dbg_info": {
     ...
     }
   }
}

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.

$ curl -b cookies -c cookies 'https://api.appnexus.com/report?id=39c4855a07e92433947886b5aabd267d'

{
 "response": {
   "status": "OK",
   "report": {
     "name": null,
     "created_on": "2015-11-17 21:27:21",
     "cache_hit": false,
     "fact_cache_hit": false,
     "fact_cache_error": null,
     "json_request": "{\"report\":{\"format\":\"csv\",\"report_interval\":\"last_48_hours\",\"columns\":[\"seller_member_name\",\"buyer_member_name\",\"imps\",\"clicks\",\"convs\"],\"report_type\":\"buyer_invoice_report\",\"filters\":[{\"buyer_member_id\":\"668\"},{\"is_delivered\":{\"value\":[\"1\"],\"operator\":\"=\"}},{\"is_valid_buyer\":{\"value\":[\"1\"],\"operator\":\"=\"}},{\"is_valid_buying_imp_type\":{\"value\":[\"1\"],\"operator\":\"=\"}}]}}",
     "header_info": "Report ID:,39c4855a07e92433947886b5aabd267d\r\nRun at:,2015-11-17 21:27:21\r\nStart date:,2015-11-15 21:00:00\r\nEnd date:,2015-11-17 20:00:00\r\nTimezone:,\r\nUser:,Huanqing Liu (171989)\r\n",
     "row_count": "309",
     "report_size": "15583",
     "internal_info": "{\"report_id\":\"39c4855a07e92433947886b5aabd267d\",\"expected_query_cost\":\"1\",\"processor\":\"20.bm-report-processor.prod.nym2\",\"last_processor_run_on\":\"20.bm-report-processor.prod.nym2\",\"cache_miss\":1,\"query\":\" SELECT seller_member_id AS alias_1,CASE WHEN transaction_type = 1 THEN 'Blank' WHEN transaction_type = 3 THEN 'Default Error' WHEN transaction_type = 4 THEN 'Default' WHEN transaction_type = 2 THEN 'PSA' WHEN transaction_type = 8 THEN 'PSA Error' WHEN transaction_type IN (5,6,7,9,10,11) THEN CAST(BUYER_MEMBER_ID AS VARCHAR(7)) ELSE 'Unknown' END AS alias_2,SUM(IMPS) AS alias_3,SUM(CLICKS) AS alias_4,sum(convs) AS alias_5  FROM agg_combined_billing fact  WHERE 1=1  AND ymdh >= '2015-11-15 21:00:00' AND ymdh < '2015-11-17 20:00:00' AND buyer_member_id IN ('668') AND is_delivered IN ('1') AND CASE WHEN has_dw_buy=1 OR is_dw_buyer=0 THEN 1 ELSE 0 END IN ('1') AND CASE WHEN transaction_type in (7, 9, 10, 11) THEN 1 ELSE 0 END IN ('1')  GROUP BY alias_1, alias_2 LIMIT 1000000001\\n-- [member_id] \\n-- [report_id] 39c4855a07e92433947886b5aabd267d\"}",
     "user_id": "171989",
     "entity_id": "0",
     "started_on": "2015-11-17 21:27:22",
     "finished_on": "2015-11-17 21:27:24",
     "query_time": "0",
     "url": "report-download?id=39c4855a07e92433947886b5aabd267d"
   },
   "execution_status": "ready",
   "_was_this_status_cached_": 0,
   "dbg_info": {
     ...
     }
   }
}

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.

Note

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.

curl -b cookies -c cookies 'https://api.appnexus.com/report-download?id=39c4855a07e92433947886b5aabd267d' > buyer_invoice_report.csv

Note

There is a limit of 100,000 rows per report when you download them as XLSX and Excel file.