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.

Report types

The Promoted Listings service lets you create the following types of reports for Promoted Listings Standard (PLS) ad campaigns that use the Cost Per Sale (CPS) funding strategy or Promoted Listings Advanced (PLA) ad campaigns that use the Cost Per Click (CPC) funding strategy:

  • Account Performance report – A summary report of the daily performance of all the seller's Promoted Listings campaigns
  • Campaign Performance report – An item level view of the performance of a campaign
  • Campaign Performance Summary report – A summary report of the daily performance of a campaign
  • Inventory Performance Summary report – An SKU (based on inventory reference IDs) view of the performance of each listing in a campaign

    Note: The Inventory Performance Summary report is not currently available; availability date is pending.

  • Listing Performance report – A listing (using eBay listing IDs) view of the performance of each listing
  • Transaction report – A report that provides transaction-level details to sellers for both PLS and PLA ad campaigns

The Promoted Listings service lets you create these two additional types of reports for PLA ad campaigns using the CPC funding strategy:

  • All Campaign Performance Summary report – A summary report of the performance data for all of a seller's campaigns
  • Keyword Performance report – A report of the keyword performance data for a specific campaign
  • Search Query Performance report – A report that offers details to sellers that help them understand buyer search patterns and behaviors, indicating which search queries most effectively led the buyers to their products and the impressions, clicks or amount of sales generated

Note: These reports are not supported for campaigns using the CPS funding strategy. Please see the Promoted Listings overview to find out more about the differences between the two available campaign funding models.

The following table provides a snapshot for each available report.

Report Type

Description

Views

Day

Campaign

Ad Group

Keyword

Listing

Inventory SKU

Transaction

Search Query

Account Performance Report This report is aggregated at the account level.

 

 

 

 

 

 

 

All Campaign Performance Summary Report This report is aggregated at every campaign level (one row per campaign).

 

 

 

 

 

 

 

Campaign Performance Report This report is for one campaign with listings.

 

 

 

 

Campaign Performance Summary Report This report is for a single campaign with a day-wise breakdown.

 

 

 

 

 

Inventory Performance Summary Report** This report is generated for inventory SKUs created through the sell APIs.

 

 

 

 

 

Listing Performance Report This report uses a set of listing IDs across campaigns or across ad groups.

 

 

 

 

 

Keyword Performance Report This report is for one campaign that uses the CPC funding strategy.

 

 

 

 

Search Query Performance Report This report is for one campaign that uses the CPC funding strategy.    

 

 

Transaction Report This report provides transaction details to sellers that use either the CPC or CPS funding strategies.

 

 

_____________________________________

**The Inventory Performance Summary report is not currently available; availability date is pending.

Report creation

Generate a report by calling the createReportTask method, which configures and begins the generation of 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. Ensure that you supply the required fields for the report that you want to generate.

Note: For Promoted Listings Advanced (PLA) sellers who create campaigns using the Cost Per Click (CPC) funding model, bulk request capability for reports is now available. Sellers can leverage this capability to create reports that return the details for all (or a large number of) campaigns, listings, keywords, etc. associated with an account. Refer to the Additional required and optional fields for specific reports section for more information.

You can use the following Marketing API methods to retrieve the information for the required and optional fields for each report type:

When specifying the timespan covered by a report, eBay honors timestamps formatted as ISO 8601 strings, which is based on the 24-hour Coordinated Universal Time (UTC) clock with local offset. For example, say you need a report response returned in the MST time zone. You would pass in the following date values when creating the report task (MST = UTC - 7 hours):

dateFrom: 2021-03-15T13:00:00-07:00
dateTo: 2021-03-17T13:00:00-07:00

The campaign metrics would be reported from 2021-03-15 6:00 MST to 2021-03-17 6:00 MST.

Refer to the following table for information about local timezone offsets for supported eBay marketplaces.

Marketplace ID

Listing Site

Timezone

Standard Time

Daylight Savings Time

EBAY_AU eBay AU Australian Western Standard Time (Perth) AWST UTC +8 AWDT UTC +9
Australian Central Western Standard Time (Eucla) ACWST UTC +8:45 N/A
Australian Central Standard Time (Adelaide) ACST UTC +9:30 ACDT UTC +10:30
Australian Eastern Standard Time (Sydney) AEST UTC +10 AEDT UTC +11
EBAY_CA eBay CA,
eBay CA-FR
Pacific Standard Time (Vancouver) PST UTC -8 PDT UTC -7
Mountain Standard Time (Edmonton) MST UTC -7 MDT UTC -6
Central Standard Time (Regina) CST UTC -6 CDT UTC -5
Newfoundland Standard Time (St. John's) NST UTC -5 NDT UTC -4
Eastern Standard Time (Montreal) EST UTC -5 EDT UTC -4
Atlantic Standard Time (Halifax) AST UTC -4 ADT UTC -3
EBAY_DE eBay DE Central European Time (Berlin) CET UTC +1 CEST UTC +2
EBAY_ES eBay ES Central European Time (Madrid) CET UTC +1 CEST UTC +2
EBAY_FR eBay FR Central European Time (Paris) CET UTC +1 CEST UTC +2
EBAY_IT eBay IT Central European Time (Rome) CET UTC +1 CEST UTC +2
EBAY_GB eBay UK Greenwich Mean Time (London) GMT UTC BST UTC +1
EBAY_US eBay US, eBay MOTORS-US Hawaii Standard Time (Honolulu) HST UTC -10 HDT UTC -9
Alaska Standard Time (Anchorage) AKST UTC -9 AKDT UTC -8
Pacific Standard Time (Los Angeles) PST UTC -8 PDT UTC -7
Mountain Standard Time (Denver) MST UTC -7 MDT UTC -6
Central Standard Time (Chicago) CST UTC -6 CDT UTC -5
Eastern Standard Time (New York City) EST UTC -5 EDT UTC -4

Report retrieval

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. However, many reports take some time to generate, and you can retrieve a report only after its status is set to SUCCESS. Call the getReportTasks method (or getReportTask with the report-task ID) to determine the status of a Promoted Listings report, which is indicated by the reportTaskStatus response field.

In some cases, the report status may be FAILED. This may be due to a number of reasons, such as required report fields being omitted in the createReportTask request, or when the data threshold has been exceeded. This is especially important to keep in mind when creating reports that utilize bulk request capabilities, as they can incorporate multiple campaigns and include a larger number of records.

Important! The data threshold for a single report is currently 200,000 records; if this threshold is exceeded, the report will fail.

In cases where the data threshold has been reached, eBay recommends that you use one of the following options to mitigate the failure:

  • Partition the report by specifying campaign IDs so that data threshold is not reached.
  • Configure the createReportTask request to cover a shorter time period.

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

Required and optional report fields

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

Required fields for all PLS reports

The following fields form the basics of all report types for Promoted Listings Standard (PLS) campaigns that use the Cost Per Sale (CPS) funding strategy. You must always supply a date range, report type, report format, and the metrics to be returned.

Required Fields

Field Formats and Values

dateFrom Format: yyyy-MM-ddThh:mm:ss.sssZ (This cannot be a future date.)
dateTo Format: yyyy-MM-ddThh:mm:ss.sssZ (This cannot be a future date.)
marketplaceId = eBay Marketplace ID Format: EBAY_{country code}

Maximum: 1
metricKeys = list of metrics to return Required: 1 or more

Valid Values:
  • impressions*: The number of times a Cost Per Sale (CPS) Promoted Listing was rendered on a page.
  • clicks*: The number of times a buyer saw a CPS Promoted Listing and then clicked through to the listing page.
  • ad_fees: The seller fees incurred from the attributed sale of their CPS Promoted Listings.
  • sales: The number of attributed CPS Promoted Listings sales that occurred within 30 days of a click on an ad.
  • sale_amount: The total sale amount (including item price, shipping, taxes, and any other applicable fees) for the attributed CPS Promoted Listings sales that occurred within 30 days of a click on an ad.
  • ctr*: The click-through-rate for a CPS Promoted Listing (clicks divided by impressions).
  • avg_cost_per_sale*: The average fee per CPS Promoted Listings sale (ad_fees divided by sales).
  • pl_transactions*: The number of CPS transactions associated with a given listing ID.

_____________________________________

* Deprecated for TRANSACTION_REPORT


Note: All metrics (except sales and sale_amount) are reported in near real-time and reconciled in 72 hours; however, the adjustments should typically be minimal.

reportFormat Valid Values: TSV_GZIP (This is currently the only supported value.)
reportType Required: 1

Valid Values:
  • ACCOUNT_PERFORMANCE_REPORT
  • CAMPAIGN_PERFORMANCE_REPORT
  • CAMPAIGN_PERFORMANCE_SUMMARY_REPORT
  • INVENTORY_PERFORMANCE_REPORT
  • LISTING_PERFORMANCE_REPORT
  • TRANSACTION_REPORT

Required fields for all PLA reports

The following fields form the basics of all report types for Promoted Listings Advanced (PLA) campaigns that use the Cost Per Click (CPC) funding strategy. You must always supply a date range, report type, report format, and the metrics to be returned.

Required Fields

Field Formats and Values

dateFrom Format: yyyy-MM-ddThh:mm:ss.sssZ (This cannot be a future date.)
dateTo Format: yyyy-MM-ddThh:mm:ss.sssZ (This cannot be a future date.)
fundingModels Valid Values (array of enum values):
  • COST_PER_CLICK
  • COST_PER_SALE

Note: This is an optional field for CPS reports. If no funding model is provided, the default value is taken as "COST_PER_SALE". The metrics should be relevant to the funding models mentioned in the request.

marketplaceId = eBay Marketplace ID Format: EBAY_{country code}

Maximum: 1
metricKeys = list of metrics to return Required: 1 or more

Valid Values:
  • cpc_impressions*: The number of times a Cost Per Click (CPC) Promoted Listing was rendered on a page.
  • cpc_clicks*: The number of times a buyer clicked through to the listing page.
  • cpc_ctr*: The click-through-rate for CPC Promoted Listings (cpc_clicks divided by cpc_impressions).
  • cpc_attributed_sales: The number of attributed CPC Promoted Listing sales that occurred within 30 days of a click on an ad.
  • cpc_sale_amount_listingsite_currency: The total sale amount (including item price, shipping, taxes, and any other applicable fees) for the attributed CPC Promoted Listing sales that occurred within 30 days of a click on an ad, expressed as a monetary value defined by the listing site currency.
  • cpc_ad_fees_listingsite_currency*: The seller fees incurred from the clicks on a CPC Promoted Listing impression, expressed as a monetary value defined by the listing site currency.
  • cpc_sale_amount_payout_currency: The total sale amount (including item price, shipping, taxes, and any other applicable fees) for the attributed CPC Promoted Listing sales that occurred within 30 days of a click on an ad, expressed as a monetary value defined by the billing currency or payout currency.
  • cpc_ad_fees_payout_currency*: The seller fees incurred from the clicks on a CPC Promoted Listing impression, expressed as a monetary value defined by the billing currency or payout currency.
  • cost_per_click*: The cost-per-click for CPC Promoted Listings, expressed as a monetary value defined by the billing currency.
  • cpc_return_on_ad_spend*: The return on ad spending (cpc_sale_amount_listingsite_currency divided by cpc_ad_fees_listingsite_currency).
  • cpc_conversion_rate*: The conversion rate for the ad (cpc_attributed_sales divided by cpc_clicks).
  • cpc_avg_cost_per_sale*: The average cost per CPC Promoted Listing sale, expressed as a monetary value defined by the billing currency (cpc_ad_fees_listingsite_currency divided by cpc_attributed_sales).
  • cpc_transactions*: The number of CPC transactions associated with a given listing ID.

_____________________________________

* Deprecated for TRANSACTION_REPORT

Note: All metrics are reported in near real-time and reconciled in 72 hours; however, the adjustments should typically be minimal.

reportFormat Valid Values: TSV_GZIP (This is currently the only supported value.)
reportType Required: 1

Valid Values:
  • ACCOUNT_PERFORMANCE_REPORT
  • ALL_CAMPAIGN_PERFORMANCE_SUMMARY_REPORT
  • CAMPAIGN_PERFORMANCE_REPORT
  • CAMPAIGN_PERFORMANCE_SUMMARY_REPORT
  • INVENTORY_PERFORMANCE_REPORT
  • LISTING_PERFORMANCE_REPORT
  • KEYWORD_PERFORMANCE_REPORT
  • SEARCH_QUERY_PERFORMANCE_REPORT
  • TRANSACTION_REPORT

Additional required and optional fields for specific reports

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

Important! If you submit a request that does not contain all of 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

dimensionKey = day
(UTC format yyyy-MM-ddThh:mm:ss.sssZ)
There are currently no optional fields for this report.

All Campaign Performance Summary report

Required Fields

Optional Fields

dimensionKey = campaign_id annotationKeys = list of annotation keys

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

Maximum: 25 IDs for PLS, or 1,000 IDs for PLA
For Promoted Listings Standard (PLS) sellers, this field is required for campaigns that use the Cost Per Sale (CPS) funding model.

For Promoted Listings Advanced (PLA) sellers, this field is optional for campaigns that use the Cost Per Click (CPC) funding model.

Note: For PLA sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.

dimensionKey = ad_group_id annotationKeys = ad_group_name
dimensionKey = campaign_id annotationKeys = list of annotation keys

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 annotationKeys = list of annotation keys

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
dimensionKey = day

Note: The dimension key "day" is only applicable to the PLA program.


Note: For PLA sellers, when the dimension key "day" is used, the timespan between the requested dateFrom and dateTo fields cannot exceed seven days.

Campaign Performance Summary report

Required Fields

Optional Fields

campaignIds = list of campaign IDs

Maximum: 25 IDs for PLS, or 1,000 IDs for PLA
For Promoted Listings Standard (PLS) sellers, this field is required for campaigns that use the Cost Per Sale (CPS) funding model.

For Promoted Listings Advanced (PLA) sellers, this field is optional for campaigns that use the Cost Per Click (CPC) funding model.

Note: For PLA sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.

dimensionKey = ad_group_id annotationKeys = ad_group_name
dimensionKey = day
(UTC format: yyyy-MM-ddThh:mm:ss.sssZ)
 
dimensionKey = campaign_id annotationKeys = list of annotation keys

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).

Inventory Performance report

Required Fields

Optional Fields

dimensionKey = ad_group_id annotationKeys = ad_group_name
dimensionKey = campaign_id annotationKeys = list of annotation keys

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 annotationKeys = list of annotation keys

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).

inventoryReferences = list of inventoryReferenceId and its inventoryReferenceType  

Keyword Performance report

Required Fields

Optional Fields

dimensionKey = ad_group_id annotationKeys = ad_group_name
dimensionKey = campaign_id annotationKeys = list of annotation keys

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 = keyword_match_type

 

dimensionKey = seller_keyword_id annotationKeys = seller_keyword

campaignIds = list of campaign IDs

Maximum: 25 IDs for PLS, or 1,000 IDs for PLA

Note: For PLA sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.

dimensionKey = day

Note: For PLA sellers, when this dimension key is used, the timespan between the requested dateFrom and dateTo fields cannot exceed seven days.

Listing Performance report

Required Fields

Optional Fields

dimensionKey = ad_group_id annotationKeys = ad_group_name
dimensionKey = campaign_id annotationKeys = list of annotation keys

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 annotationKeys = list of annotation keys

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
  listingIds = list of eBay listing IDs

Note: For Promoted Listings Advanced (PLA) sellers, leave this field blank to retrieve the details for all listings associated with the specified campaign IDs (or all campaigns associated with your account, if no campaign IDs are specified), or specify the listing IDs for which you would like to retrieve the listing-specific details.

dimensionKey = day

Note: For PLA sellers, when this dimension key is used, the timespan between the requested dateFrom and dateTo fields cannot exceed seven days.

Search Query Performance report

Required Fields

Optional Fields

dimensionKey = ad_group_id annotationKeys = ad_group_name
dimensionKey = campaign_id annotationKeys = list of annotation keys

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 = search_query  

campaignIds = list of campaign IDs

Maximum: 25 IDs for PLS, or 1,000 IDs for PLA

Note: For PLA sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.

dimensionKey = day

Note: For PLA sellers, when this dimension key is used, the timespan between the requested dateFrom and dateTo fields cannot exceed seven days.

dimensionKey = keyword_match_type

Note: Only exact and phrase match types are currently supported.

dimensionKey = seller_keyword_id

annotationKeys = seller_keyword

Important! This field cannot be used without the keyword_match_type. Report task requests specifying only the seller_keyword_id will fail.

Transaction report

Note: The following list contains API capabilities that are deprecated and scheduled for decommission:

  • Multiple value support for the fundingModels array of the createReportTask method
  • Support for specific metric keys used in Transaction reports for either funding model: impressions, clicks, ctr, avg_cost_per_sale, pl_transactions, cpc_impressions, cpc_clicks, cpc_ctr, cpc_conversion_rate, cpc_return_on_ad_spend, cpc_avg_cost_per_sale, cpc_transactions, cpc_ad_fees_listingsite_currency, cpc_ad_fees_payout_currency, cost_per_click.

See API Deprecation Status for additional details.

Required Fields

Optional Fields

dimensionKey = transaction_id  
dimensionKey = listing_id annotationKeys = list of annotation keys
Valid Values: listing_title, listing_price, listing_start_date, listing_end_date, listing_quantity_sold, listing_quantity_available
fundingModels = COST_PER_CLICK or COST_PER_SALE Valid Values (array of enum values):
  • COST_PER_CLICK
  • COST_PER_SALE

Note: This report can be used for either PLA or PLS campaigns. The metrics returned will be relevant to the funding model specified in the request.

dimensionKey = day

 

dimensionKey = campaign_id
annotationKeys = list of annotation keys
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).

 

 

COST_PER_CLICK (PLA campaigns, only)

 

dimensionKey = ad_group_id
annotationKeys = ad_group_name

 

dimensionKey = seller_keyword_id
annotationKeys = seller_keyword

Important! This field cannot be used without the keyword_match_type. Report task requests specifying only the seller_keyword_id will fail.

 

dimensionKey = keyword_match_type

Note: Only exact and phrase match types are currently supported.