Skip to main content

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 500,000 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.

HeaderTypeDescription
Content-TypestringThis 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

Request fields

Input container/fieldTypeDescription
additionalRecordsarray 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

campaignIdsarray 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

channelsarray 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

dateFromstring

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

dateTostring

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

dimensionsarray 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.annotationKeysarray of string

A list of annotations associated with the dimension of the report.

Occurrence: Optional

dimensions.dimensionKeystring

The name of the dimension on which the report is based.

A dimension is an attribute to which the report data applies.

Occurrence: Required

fundingModelsarray 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

inventoryReferencesarray 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.inventoryReferenceIdstring

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

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

listingIdsarray 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

marketplaceIdMarketplaceIdEnum

The unique identifier for the eBay marketplace on which the report is based.

Occurrence: Required

metricKeysarray 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

reportFormatReportFormatEnum

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

reportTypeReportTypeEnum

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.

HeaderMeaning
LocationThe 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.
WarningCarries 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.

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

Error codes

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

CodeDomainCategoryMeaning
35001API_MARKETINGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
35012API_MARKETINGREQUESTThe 'inventoryReferenceId' {inventoryReferenceId} is not valid.
35013API_MARKETINGREQUESTThe 'listingId' {listingId} is not valid. Correct the 'listingId' and try the call again.
35040API_MARKETINGREQUESTThe 'inventoryReferenceType' {inventoryReferenceType} is not supported.
35041API_MARKETINGREQUESTA 'marketplaceId' is required. Supported marketplaces are: {supportedMarketplaces}
35045API_MARKETINGREQUESTNo campaign found for {campaignId}.
35051API_MARKETINGBUSINESSThe 'marketplaceId' {marketplaceId} is not supported. Supported marketplaces are: {supportedMarketplaces}
35068API_MARKETINGBUSINESSYou have exceeded the maximum number of listing IDs. Only {maxSupportedListings} listings are supported per call.
35089API_MARKETINGREQUESTYou are currently not authorized to access the Promoted Listings Advanced program. Please contact support
35090API_MARKETINGREQUESTdateFrom and dateTo span exceeds maximum allowed. Only up to {maxDayRange} days are supported.
35091API_MARKETINGREQUEST'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}
35100API_MARKETINGREQUESTCampaign ID is required for this call.
35101API_MARKETINGBUSINESSYou have exceeded the maximum number of campaign IDs. Only {maxSupportedCampaigns} campaigns are supported per call.
35102API_MARKETINGREQUESTThe {date_key} date is required for this call.
35103API_MARKETINGREQUESTThe date cannot be in future.
35104API_MARKETINGREQUESTThe report start date {dateFrom} cannot be after the end date {dateTo}.
35105API_MARKETINGREQUESTThe report 'dateFrom' {dateFrom} is out of range. Reports are limited up to {maxDays} days in the past.
35106API_MARKETINGREQUESTThe 'dimensionKey' {dimensionKey} is not valid. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls.
35107API_MARKETINGREQUESTThe '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.
35108API_MARKETINGREQUESTThe '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.
35111API_MARKETINGREQUESTThe 'inventoryReferenceId' {inventoryReferenceId} is not valid.
35112API_MARKETINGBUSINESSThe maximum number {maxSupportedInventoryReferences} of inventory references has been exceeded.
35113API_MARKETINGREQUESTThe listing ID is required for this call.
35114API_MARKETINGREQUESTThe 'reportType' is invalid. Valid values are: {supportedReportTypes}.
35115API_MARKETINGREQUESTThe '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.
35118API_MARKETINGREQUESTThe 'reportFormat' is missing or invalid. Valid values are: {supportedReportFormats}
35119API_MARKETINGREQUESTThe minimum set of 'dimensionKey' is not provided for the 'reportType' {reportType}. Minimum required dimensionKeys are: {minimumDimensionKeys}
35120API_MARKETINGREQUESTAt least one 'metricKey' must be provided for 'reportType' {reportType}. Valid metricKeys are: {supportedMetricKeys}
35121API_MARKETINGREQUESTThe 'fundingModel' is invalid. Valid values are: {supportedFundingModels}.
35122API_MARKETINGREQUESTThe metric key is not supported for the funding model.
35123API_MARKETINGREQUESTThe 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel}
35124API_MARKETINGREQUESTMultiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}
35125API_MARKETINGREQUESTThe 'channel' is invalid. Valid values are: {supportedChannels}.
35126API_MARKETINGREQUESTMultiple channels are not supported. Please use one of the following channels: {supportedChannels}
35127API_MARKETINGREQUESTThe 'channels' are not supported for the 'fundingModel' {fundingModel}
35128API_MARKETINGREQUESTThe 'dimensionKey' {dimensionKey} is not valid for the 'channels' {supportedChannels}
35129API_MARKETINGREQUESTThe 'metricKey' {metricKey} is not supported for the 'channels' {supportedChannels}
35130API_MARKETINGREQUESTThe 'annotationKey' {annotationKey} is not supported for the 'fundingModel' {fundingModel}.
35131API_MARKETINGREQUESTThe '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

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

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

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.