POST /ad_report_task

Note: Using multiple funding models in one report is deprecated. If multiple funding models are used, a Warning will be returned in a header. This functionality will be decommissioned on April 3, 2023. See API Deprecation Status for details.

This method creates a report task, which generates a Promoted Listings report based on the values specified in the call.

The report is generated based on the criteria you specify, including the report type, the report's dimensions and metrics, the report's start and end dates, the listings to include in the report, and more. Metrics are the quantitative measurements in the report while dimensions specify the attributes of the data included in the reports.

When creating a report task, you can specify the items you want included in the report. The items you specify, using either listingId or inventoryReference values, must be in a Promoted Listings campaign for them to be included in the report.

For details on the required and optional fields for each report type, see Promoted Listings reporting.

This call returns the URL to the report task in the Location response header, and the URL includes the report-task ID.

Reports often take time to generate and it's common for this call to return an HTTP status of 202, which indicates the report is being generated. Call getReportTasks (or getReportTask with the report-task ID) to determine the status of a Promoted Listings report. When a report is complete, eBay sets its status to SUCCESS and you can download it using the URL returned in the reportHref field of the getReportTask call. Report files are tab-separated value gzip files with a file extension of .tsv.gz.

Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.

Note: This call fails if you don't submit all the required fields for the specified report type. Fields not supported by the specified report type are ignored. Call getReportMetadata to retrieve a list of the fields you need to configure for each Promoted Listings report type.

Servers

https://api.ebay.com{basePath}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`dimensions[]`	Array	No	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 Promoted Listings reporting.
`dimensions[].annotationKeys[]`	Array	No	A list of annotations associated with the dimension of the report.
`dimensions[].dimensionKey`	String	No	The name of the dimension on which the report is based. A dimension is an attribute to which the report data applies.
`reportFormat`	String	No	The file format of the report. Currently, the only supported format is `TSV_GZIP`, which is a gzip file with tab separated values. For implementation help, refer to eBay API documentation
`fundingModels[]`	Array	No	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`. Note: Multiple value support for the fundingModels array has been deprecated. See API Deprecation Status for information. Valid Values: `COST_PER_SALE` `COST_PER_CLICK` Required if the campaign funding model is Cost Per Click (CPC).
`additionalRecords[]`	Array	No	A list of additional records that shall be included in the report, such as non-performing data. Note: Additional records are only applicable to Promoted Listings Advanced (PLA) campaigns that use the Cost Per Click (CPC) funding model. Valid Value: `NON_PERFORMING_DATA`
`dateFrom`	String	No	The date defining the start of the timespan covered by the report. Format the timestamp as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock with local offset. Note: The date specified cannot be a future date. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2021-03-15T13:00:00-07:00`
`inventoryReferences[]`	Array	No	You can use this field to supply an array of items to include in the report if you manage your inventory with the Inventory API. This field is mutually exclusive with the listingIds field; if you populate this field, do not populate the listingIds field. An inventory reference identifies an item in your inventory using a pair of values, where the inventoryReferenceId can be either a seller-defined SKU value or an inventoryItemGroupKey, where an inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing). Couple the inventoryReferenceId with an inventoryReferenceType identifier to fully identify an item in your inventory. Maximum: 500 items Required if you do not supply an array of listingId values or if you set reportType to `INVENTORY_PERFORMANCE_REPORT`.
`inventoryReferences[].inventoryReferenceType`	String	No	Indicates the type of item indicated by the inventoryReferenceId. This value can be set to either `INVENTORY_ITEM` or `INVENTORY_ITEM_GROUP` (if the ID points to a multi-variation listing). Required if if you supply an inventoryReferenceId. For implementation help, refer to eBay API documentation
`inventoryReferences[].inventoryReferenceId`	String	No	The seller's inventory reference ID for an item that is managed with the Inventory API. An inventory reference is either the ID of a single listing or the ID of the parent of an item group listing (a multi-variation listing, such as a shirt that is available in multiple sizes and colors). Required if if you supply an inventoryReferenceType.
`listingIds[]`	Array	No	Use this field to supply an array of listing IDs you want to include in the report. A listing ID is the eBay listing identifier that is generated when the listing is created. This field accepts listing ID values generated with both the Inventory API and the eBay Traditional APIs, such as the Trading and Finding APIs. Important: This field is mutually exclusive with the inventoryReferences field; if you populate this field, do not populate the inventoryReferences field. For Promoted Listings Standard (PLS) sellers, this field is required if you do not supply an array of inventoryReferences values or if you set the reportType to `LISTING_PERFORMANCE_REPORT`. 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. Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details. Maximum: 500 listings
`marketplaceId`	String	No	The ID for the eBay marketplace on which the report is based. Maximum: 1 For implementation help, refer to eBay API documentation
`reportType`	String	No	The type of report to be generated, such as `ACCOUNT_PERFORMANCE_REPORT` or `CAMPAIGN_PERFORMANCE_REPORT`. Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. Maximum: 1 For implementation help, refer to eBay API documentation
`campaignIds[]`	Array	No	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. For Promoted Listings Standard (PLS) sellers, this field is required if the reportType is set to `CAMPAIGN_PERFORMANCE_REPORT` or `CAMPAIGN_PERFORMANCE_SUMMARY_REPORT`. For Promoted Listings Advanced (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. Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details. Maximum: 25 IDs for PLS 1,000 IDs for PLA
`metricKeys[]`	Array	No	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 Promoted Listings reporting. Minimum: 1
`dateTo`	String	No	The date defining the end of the timespan covered by the report. As with the dateFrom field, format the timestamp as an ISO 8601 string. 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. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2021-03-17T13:00:00-07:00`

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.