createReportTask: eBay Marketing API | eBay Developers Program

POST/ad_report_task

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.

Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.

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

Input

Resource URI

POST https://api.ebay.com/sell/marketing/v1/ad_report_task

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required

Header

Type

Description

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.marketing

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* CreateReportTask */

"additionalRecords" : [

"AdditionalRecordEnum : [NON_PERFORMING_DATA]"

"campaignIds" : [

"string"

"channels" : [

"ChannelEnum : [ON_SITE,OFF_SITE]"

"dateFrom" : "string",

"dateTo" : "string",

"dimensions" : [

{ /* Dimension */

"annotationKeys" : [

"string"

"dimensionKey" : "string"

}

"fundingModels" : [

"FundingModelEnum : [COST_PER_SALE,COST_PER_CLICK]"

"inventoryReferences" : [

{ /* InventoryReference */

"inventoryReferenceId" : "string",

"inventoryReferenceType" : "InventoryReferenceTypeEnum : [INVENTORY_ITEM,INVENTORY_ITEM_GROUP]"

}

"listingIds" : [

"string"

"marketplaceId" : "MarketplaceIdEnum : [EBAY_AT,EBAY_AU,EBAY_BE...]",

"metricKeys" : [

"string"

"reportFormat" : "ReportFormatEnum : [TSV_GZIP]",

"reportType" : "ReportTypeEnum : [ACCOUNT_PERFORMANCE_REPORT,ALL_CAMPAIGN_PERFORMANCE_SUMMARY_REPORT,CAMPAIGN_PERFORMANCE_REPORT...]"

}

Request fields

Input container/field	Type	Description
additionalRecords	array of AdditionalRecordEnum	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 priority strategy campaigns that use the Cost Per Click (CPC) funding model. Valid Value: `NON_PERFORMING_DATA` Occurrence: Optional
campaignIds	array of string	A list of campaign IDs to be included in the report task. Use the getCampaigns method to retrieve a list of the current campaign IDs for a seller. For general campaign strategy sellers, this field is required if the reportType is set to `CAMPAIGN_PERFORMANCE_REPORT` or `CAMPAIGN_PERFORMANCE_SUMMARY_REPORT`. For priority strategy campaign 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: 1,000 IDs Occurrence: Conditional
channels	array of ChannelEnum	The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign. If no value is entered, this field will default to `ON_SITE`. Multiple channels are not supported. Note: Channels are only applicable for campaigns that use the Cost Per Click (CPC) funding model. Valid Values: `ON_SITE` `OFF_SITE` This field is required and must be set to `OFF_SITE` if the report is for a Offsite Ads campaign. Occurrence: Conditional
dateFrom	string	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` Occurrence: Required
dateTo	string	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` Occurrence: Required
dimensions	array of Dimension	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. Occurrence: Required
dimensions.annotationKeys	array of string	A list of annotations associated with the dimension of the report. Occurrence: Optional
dimensions.dimensionKey	string	The name of the dimension on which the report is based. A dimension is an attribute to which the report data applies. Occurrence: Required
fundingModels	array of FundingModelEnum	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). Occurrence: Conditional
inventoryReferences	array of InventoryReference	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`. Occurrence: Conditional
inventoryReferences.inventoryReferenceId	string	The unique identifier of a single-item listing or a multi-variation listing. To create an ad for a single-item listing, set the inventoryReferenceType value to `INVENTORY_ITEM` and specify an item ID or a SKU (if the SKU is defined in the listing). To create an ad for a multi-variation listing, set the inventoryReferenceType value to `INVENTORY_ITEM_GROUP` and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API. Required if if you supply an inventoryReferenceType. Occurrence: Conditional
inventoryReferences.inventoryReferenceType	InventoryReferenceTypeEnum	Indicates the type of item indicated by the inventoryReferenceId. This value can be set to either `INVENTORY_ITEM` or `INVENTORY_ITEM_GROUP`. Required if if you supply an inventoryReferenceId. Occurrence: Conditional
listingIds	array of string	Use this field to supply an array of eBay listing IDs you want to include in the report. Important: This field is mutually exclusive with the inventoryReferences field; if you populate this field, do not populate the inventoryReferences field. For general campaign strategy 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 priority strategy campaign 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 Occurrence: Conditional
marketplaceId	MarketplaceIdEnum	The unique identifier for the eBay marketplace on which the report is based. Occurrence: Required
metricKeys	array of string	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 Occurrence: Required
reportFormat	ReportFormatEnum	The file format of the report. Currently, the only supported format is `TSV_GZIP`, which is a gzip file with tab separated values. Occurrence: Required
reportType	ReportTypeEnum	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 Occurrence: Required

Output

HTTP response headers

See HTTP response headers for details.

Header	Meaning
Location	The location response header contains the URL to the newly created report task. The URL includes the eBay-assigned `reportTaskId`, which you can use to reference the report task.
Warning	Carries additional information about the status or transformation of a message that might not be reflected in the status code.

Response payload

This call has no payload.

Response fields

This call has no field definitions.

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
202	Accepted
400	Bad Request
403	Forbidden
409	Conflict
500	Internal Server error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
35001	API_MARKETING	APPLICATION	There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
35012	API_MARKETING	REQUEST	The 'inventoryReferenceId' {inventoryReferenceId} is not valid.
35013	API_MARKETING	REQUEST	The 'listingId' {listingId} is not valid. Correct the 'listingId' and try the call again.
35040	API_MARKETING	REQUEST	The 'inventoryReferenceType' {inventoryReferenceType} is not supported.
35041	API_MARKETING	REQUEST	A 'marketplaceId' is required. Supported marketplaces are: {supportedMarketplaces}
35045	API_MARKETING	REQUEST	No campaign found for {campaignId}.
35051	API_MARKETING	BUSINESS	The 'marketplaceId' {marketplaceId} is not supported. Supported marketplaces are: {supportedMarketplaces}
35068	API_MARKETING	BUSINESS	You have exceeded the maximum number of listing IDs. Only {maxSupportedListings} listings are supported per call.
35089	API_MARKETING	REQUEST	You are currently not authorized to access the Promoted Listings Advanced program. Please contact support
35090	API_MARKETING	REQUEST	dateFrom and dateTo span exceeds maximum allowed. Only up to {maxDayRange} days are supported.
35091	API_MARKETING	REQUEST	'additionalRecords' are supported only with COST_PER_CLICK FundingModel and non-performing data is applicable for account level reports with no Day level dimension. 'additionalRecords' are applicable for reportTypes {supportedReportTypes}
35100	API_MARKETING	REQUEST	Campaign ID is required for this call.
35101	API_MARKETING	BUSINESS	You have exceeded the maximum number of campaign IDs. Only {maxSupportedCampaigns} campaigns are supported per call.
35102	API_MARKETING	REQUEST	The {date_key} date is required for this call.
35103	API_MARKETING	REQUEST	The date cannot be in future.
35104	API_MARKETING	REQUEST	The report start date {dateFrom} cannot be after the end date {dateTo}.
35105	API_MARKETING	REQUEST	The report 'dateFrom' {dateFrom} is out of range. Reports are limited up to {maxDays} days in the past.
35106	API_MARKETING	REQUEST	The 'dimensionKey' {dimensionKey} is not valid. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls.
35107	API_MARKETING	REQUEST	The 'dimensionKey' {dimensionKey} is not supported for the 'reportType' {reportType}. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls.
35108	API_MARKETING	REQUEST	The 'annotationKey' {annotationKey} is not supported for the 'dimensionKey' {dimensionKey}. To see the supported annotation and dimension keys for a report, use one of the 'Get Metadata' calls.
35111	API_MARKETING	REQUEST	The 'inventoryReferenceId' {inventoryReferenceId} is not valid.
35112	API_MARKETING	BUSINESS	The maximum number {maxSupportedInventoryReferences} of inventory references has been exceeded.
35113	API_MARKETING	REQUEST	The listing ID is required for this call.
35114	API_MARKETING	REQUEST	The 'reportType' is invalid. Valid values are: {supportedReportTypes}.
35115	API_MARKETING	REQUEST	The 'metricKey' {metricKey} is not supported for the 'reportType' {reportType}. To see the supported metric keys for a report, use one of the 'Get Metadata' calls.
35118	API_MARKETING	REQUEST	The 'reportFormat' is missing or invalid. Valid values are: {supportedReportFormats}
35119	API_MARKETING	REQUEST	The minimum set of 'dimensionKey' is not provided for the 'reportType' {reportType}. Minimum required dimensionKeys are: {minimumDimensionKeys}
35120	API_MARKETING	REQUEST	At least one 'metricKey' must be provided for 'reportType' {reportType}. Valid metricKeys are: {supportedMetricKeys}
35121	API_MARKETING	REQUEST	The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}.
35122	API_MARKETING	REQUEST	The metric key is not supported for the funding model.
35123	API_MARKETING	REQUEST	The 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel}
35124	API_MARKETING	REQUEST	Multiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}
35125	API_MARKETING	REQUEST	The 'channel' is invalid. Valid values are: {supportedChannels}.
35126	API_MARKETING	REQUEST	Multiple channels are not supported. Please use one of the following channels: {supportedChannels}
35127	API_MARKETING	REQUEST	The 'channels' are not supported for the 'fundingModel' {fundingModel}
35128	API_MARKETING	REQUEST	The 'dimensionKey' {dimensionKey} is not valid for the 'channels' {supportedChannels}
35129	API_MARKETING	REQUEST	The 'metricKey' {metricKey} is not supported for the 'channels' {supportedChannels}
35130	API_MARKETING	REQUEST	The 'annotationKey' {annotationKey} is not supported for the 'fundingModel' {fundingModel}.
35131	API_MARKETING	REQUEST	The 'annotationKey' {annotationKey} is not supported for the 'channels' {supportedChannels}

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Create a Report Task

Sample 2: Create a Report Task in the MST time zone

Sample 3: Create a Report Task in the PST time zone

Sample 1: Create a Report Task

This sample creates a Campaign Performance report.

Input

The inputs are the dateFrom, dateTo, reportFormat, reportType, metricKeys, campaignIds, and dimensionKey.

POSThttps://api.ebay.com/sell/marketing/v1/ad_report_task

Output

A successful call returns the HTTP status code 201 Created and the service begins generating the report.

In addition, the response includes a location response header that contains the URI to the newly created report task. The returned URI also includes the ID to the newly created promotion.

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.

Sample 2: Create a Report Task in the MST time zone

This sample creates a Campaign Performance report with the response returned in the MST time zone. This example returns the report for the period 2021-03-15 6:00 MST to 2021-03-17 6:00 MST.

Input

The inputs are the dateFrom, dateTo, reportFormat, reportType, metricKeys, campaignIds, and dimensionKey. 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"

POSThttps://api.ebay.com/sell/marketing/v1/ad_report_task

Output

Sample 3: Create a Report Task in the PST time zone

This sample creates a Campaign Performance report with the response returned in the PST time zone. This example returns the report for the period 2021-03-15 5:00 PST to 2021-03-17 5:00 PST.

Input

The inputs are the dateFrom, dateTo, reportFormat, reportType, metricKeys, campaignIds, and dimensionKey. You would pass in the following date values when creating the report task (PST = UTC - 8 hours):
"dateFrom": "2021-03-15T13:00:00-08:00"
"dateTo": "2021-03-17T13:00:00-08:00"

POSThttps://api.ebay.com/sell/marketing/v1/ad_report_task