eBay Campaign Reports Technical Scope

Promoted Listings Reports

In order to get an report how a specific campaign/promotion is performing we will need to follow two steps first to createReportTask and then getReport

In order to generate a report you need to insert a new row in eBay Reports table. Each Campaign can have many reports. Once we request a new report we will need to store the report id from the response header with the relevant status in Hemi. If we request a new report task using the action button report we will need to push the following request: POST https://api.ebay.com/sell/marketing/v1/ad_report_task

{
  "campaignIds": [
    "string"
  ],
  "dateFrom": "string",
  "dateTo": "string",
  "dimensions": [
    {
      "annotationKeys": [
        "string"
      ],
      "dimensionKey": "string"
    }
  ],
  "fundingModels": [
    "FundingModelEnum"
  ],
  "inventoryReferences": [
    {
      "inventoryReferenceId": "string",
      "inventoryReferenceType": "InventoryReferenceTypeEnum : [INVENTORY_ITEM,INVENTORY_ITEM_GROUP]"
    }
  ],
  "listingIds": [
    "string"
  ],
  "marketplaceId": "MarketplaceIdEnum : [EBAY_AT,EBAY_AU,EBAY_BE,EBAY_CA,EBAY_CH,EBAY_CN,EBAY_CZ,EBAY_DE,EBAY_DK,EBAY_ES,EBAY_FI,EBAY_FR,EBAY_GB,EBAY_GR,EBAY_HK,EBAY_HU,EBAY_ID,EBAY_IE,EBAY_IL,EBAY_IN,EBAY_IT,EBAY_JP,EBAY_MY,EBAY_NL,EBAY_NO,EBAY_NZ,EBAY_PE,EBAY_PH,EBAY_PL,EBAY_PR,EBAY_PT,EBAY_RU,EBAY_SE,EBAY_SG,EBAY_TH,EBAY_TW,EBAY_US,EBAY_VN,EBAY_ZA,EBAY_HALF_US,EBAY_MOTORS_US]",
  "metricKeys": [
    "string"
  ],
  "reportFormat": "ReportFormatEnum : [TSV_GZIP]",
  "reportType": "ReportTypeEnum : [ACCOUNT_PERFORMANCE_REPORT,ALL_CAMPAIGN_PERFORMANCE_SUMMARY_REPORT,CAMPAIGN_PERFORMANCE_REPORT,CAMPAIGN_PERFORMANCE_SUMMARY_REPORT,INVENTORY_PERFORMANCE_REPORT,LISTING_PERFORMANCE_REPORT,KEYWORD_PERFORMANCE_REPORT,TRANSACTION_REPORT,SEARCH_QUERY_PERFORMANCE_REPORT]"
}

A list of campaign IDs to be included in the report task. Call getCampaigns to get a list of the current campaign IDs for a seller.  Note: The API currently supports only a single campaign ID per report task. | | dateFrom | eBay Report > Start Date OR Campaign Ebay > Start Date | By default we need to pick the date from the campaign/promotion or if we populate this field we will have custom period | | dateTo | eBay Report > End Date OR Campaign Ebay > End Date OR CURRENT_DATE | By default we need to pick the date from the campaign/promotion or if we populate this field we will have custom period

Note: The date specified cannot be a future date. Additionally, the time specified must be a later time than that specified in the dateFrom field.

Thus we need to check if End Date > Current Date to get the Current Date | | dimensions | For report type CAMPAIGN_PERFORMANCE_REPORT :

"dimensions": [ { "annotationKeys": [ "campaign_name", "campaign_start_date", "campaign_end_date" ], "dimensionKey": "campaign_id" }, { "annotationKeys": [ "listing_title", "listing_quantity_sold", "listing_quantity_available", "listing_start_date", "listing_end_date", "listing_price" ], "dimensionKey": "listing_id" } ] | The list of the dimensions applied to the report. A dimension is an attribute to which the report data applies. For example, if you set dimensionKey to campaign_id in a Campaign Performance Report, the data will apply to the entire ad campaign. For information on the dimensions and how to specify them, see Reading Promoted Listings reports. | | | For report type CAMPAIGN_PERFORMANCE_SUMMARY_REPORT :

"dimensions": [ { "annotationKeys": [ "campaign_name", "campaign_start_date", "campaign_end_date" ], "dimensionKey": "campaign_id" }, { "annotationKeys": [], "dimensionKey": "day" } ] | | | fundingModels | Campaign Ebay > Funding Model | The funding model for the campaign that shall be included in the report. Note: The default funding model for Promoted Listings reports is COST_PER_SALE. Valid Values: • COST_PER_SALE • COST_PER_CLICK (Available only for PLA Phase2) Required if the campaign funding model is Cost Per Click (CPC). | | metricKeys | We would like to include all the metrics: • 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) • pl_transactions | The list of metrics to be included in the report. Metrics are the quantitative measurements compiled into the report and the data returned is based on the specified dimension of the report. For example, if the dimension is campaign, the metrics for number of sales would be the number of sales in the campaign. However, if the dimension is listing, the number of sales represents the number of items sold in that listing. For information on metric keys and how to set them, see Reading Promoted Listings reports. Minimum: 1 Occurrence: Required | | reportFormat | TSV_GZIP | The file format of the report. Currently, the only supported format is TSV_GZIP, which is a gzip file with tab separated values. | | reportType | eBay Report > Report Type | Dropdown field with enums

The type of report to be generated, such as 

CAMPAIGN_PERFORMANCE_SUMMARY_REPORTCAMPAIGN_PERFORMANCE_REPORT Maximum: 1 Occurrence: Required | | listingIds | Campaign Ebay Listing > Channel Item Id | Get all listings in the campaign and add their Channel IDs here as array. | | marketplaceId | Account > CountryEdit | Prefix the value from this field with “EBAY_”. In the end we should get something like “EBAY_GB”. We will have internal mapping based on the Account > Country to generate the marketplace ID | | | eBay Report > External Status | keep track of the status of the report | | | eBay Report > External ID | eBay Report Id | | | eBay Report > Campaign or Promotion | For internal user to be able to check for which campaign/promotion is the report |

Once we request a new report in order to download the file we need to get it with: GET https://api.ebay.com/sell/marketing/v1/ad_report_task/{report_task_id}

To see if the report has been generated, call getReportTask using the returned report task ID. In the response, check the reportTaskStatus field. If this field is SUCCESS, the response will also contain the reportHref field, which is the URL to the generated report. This method has no response payload.

Which means we will periodically check if the report is ready and if yes we update the status and store the report url from where we can download the file. Please note it is up to you if we will host locally the reports or use the eBay URL.