Creating Promoted Listings reports

Promoted Listings reports let you create client-side dashboards using information gained from a variety of report types.

The reports provide performance metrics according to a range of configurable dimensions. Once you generate a report, use the report data to dynamically display information that sellers can use to analyze their campaign performances. Sellers can use this information to adjust their marketing strategies according to live data.

The Promoted Listings service lets you create the following types of reports:

  • Account Performance report – A summary report of the daily performance of all the seller's Promoted Listings campaigns

  • Campaign Performance Summary report – A summary report of the daily performance of a campaign

  • Campaign Performance report – An item level view of the performance of a campaign

  • Listing Performance report – A listing (using eBay listing Ids) view of the performance of each listing

  • Inventory Performance Summary report – An SKU (based on inventory reference IDs) view of the performance of each listing in a campaign

Generating and getting reports

Generate a report by calling createReportTask, which configures and begins the generation the report. The type of report that is generated depends on how you configure your createReportTask call.

Each report type uses a different set of required fields, and each type also supports optional fields that let you further configure the reports. You must make sure to supply the required fields for the report you want to generate. Use the getReportMetadata and getReportMetadataForReportType methods to get the required and optional fields for each report type.

If your request to createReportTask is successful, the URI to the report task, which includes the report task ID, is returned in the Location response header.

Many reports take some time to generate and you can retrieve a report only after its status is set to SUCCESS. Call getReportTasks (or getReportTask with the report-task ID) to determine the status of a Promoted Listings report.

When a report task is no longer needed, delete the report using deleteReportTasks.

Required and optional report fields

The following sections detail the fields that are required and optional for each report type.

Required fields for all reports

The following fields form the basics of all report types. You must always supply a date range, report type, report format, and the metrics to be returned.

Required Fields

Field Formats

dateFrom Format: yyyy-MM-ddThh:mm:ss.sssZ
dateTo Format: yyyy-MM-ddThh:mm:ss.sssZ
reportFormat Valid Values: TSV_GZIP (Currently the only supported value.)
reportType Required: 1

Valid Values:
   ACCOUNT_PERFORMANCE_REPORT
   CAMPAIGN_PERFORMANCE_SUMMARY_REPORT
   CAMPAIGN_PERFORMANCE_REPORT
   LISTING_PERFORMANCE_REPORT
   INVENTORY_PERFORMANCE_REPORT
metricKeys = list of metrics to return Required: 1 or more

Valid Values:
  • impressions (The number of times a Promoted Listing was rendered on a page.)
  • clicks (The number of times a buyer saw a Promoted Listing and then clicked through to the listing page.)
  • ad_fees (The seller fees incurred from the sale of their Promoted Listings.)
  • sales (The number of sales.)
  • sale_amount (Total amount of sales.)
  • ctr (click-through-rate: clicks divided by impressions)
  • avg_cost_per_sale (The average fee per sale. ad_fees divided by sales)

Additional required and optional fields for specific reports

The following lists the additional required fields and all the optional fields for each report.

Important! If you submit a request that does not contain all the required fields for the specified report, the call will fail. If you submit a request that contains fields that are not supported by the specified report, the unsupported fields are ignored but the report is still generated (as long as all the required fields for the report are specified).

Account Performance report

Required Fields

Optional Fields

marketplaceId = eBay Marketplace ID  
dimensionKey = day
(UTC format yyyy-MM-ddThh:mm:ss.sssZ)
 

Campaign Performance Summary report

Required Fields

Optional Fields

campaignIds = list of campaign IDs
(Currently, limited to 1 ID)
 
dimensionKey = day
(UTC format: yyyy-MM-ddThh:mm:ss.sssZ)
 
dimensionKey = campaign_id annotationKey
Valid Values: campaign_name, campaign_start_date, campaign_end_date

Note: The value for campaign_start_date and campaign_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).

Campaign Performance report

Required Fields

Optional Fields

campaignIds = list of campaign IDs
(Currently limited to 1 ID)
 
dimensionKey = campaign_id annotationKey
Valid Values: campaign_name, campaign_start_date, campaign_end_date

Note: The value for campaign_start_date and campaign_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
dimensionKey = listing_id annotationKey
Valid Values: listing_title, listing_quantity_sold, listing_quantity_available, listing_start_date, listing_end_date, listing_price

Note: The value for listing_start_date and listing_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
dimensionKey = inventory_reference_id
dimensionKey = inventory_reference_type

Listing Performance report

Required Fields

Optional Fields

listingIds = list of eBay listing IDs  
dimensionKey = campaign_id annotationKey
Valid Values: campaign_name, campaign_start_date, campaign_end_date

Note: The value for campaign_start_date and campaign_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
dimensionKey = listing_id annotationKey
Valid Values: listing_title, listing_quantity_sold, listing_quantity_available, listing_start_date, listing_end_date, listing_price

Note: The value for listing_start_date and listing_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
dimensionKey = inventory_reference_id
dimensionKey = inventory_reference_type

Inventory Performance report

Required Fields

Optional Fields

inventoryReferences = list of inventoryReferenceId and its inventoryReferenceType  
marketplaceId = eBay Marketplace ID  
dimensionKey = campaign_id annotationKey
Valid Values: campaign_name, campaign_start_date, campaign_end_date

Note: The value for campaign_start_date and campaign_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).
dimensionKey = inventory_reference_id  
dimensionKey = inventory_reference_type  
dimensionKey = listing_id

annotationKey
Valid Values: listing_title, listing_quantity_sold, listing_quantity_available, listing_start_date, listing_end_date, listing_price

Note: The value for listing_start_date and listing_end_date are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).