marketing APIv1.10.0

createReportTask

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 Creating Promoted Listings reports.

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

Input

Resource URI (production)

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

URI parameters

HTTP request headers

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

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.

Input container/fieldTypeDescription
campaignIdsarray of stringA 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.



Maximum: 1

Required if reportType is set to CAMPAIGN_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_SUMMARY_REPORT.

Occurrence: Conditional

dateFromstringThe 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

dateTostringThe 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: Optional

dimensionsarray of DimensionThe 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.

Occurrence: Required

dimensions.annotationKeysarray of stringA list of annotations associated with the dimension of the report.

Occurrence: Optional

dimensions.dimensionKeystringThe name of the dimension on which the report is based.

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

Occurrence: Required

inventoryReferencesarray of InventoryReferenceYou 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.inventoryReferenceIdstringThe 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.

Occurrence: Conditional

inventoryReferences.inventoryReferenceTypeInventoryReferenceTypeEnumIndicates 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.

Occurrence: Conditional

listingIdsarray of stringUse this field to supply a array of the listing ID you want to include in the report.

This field is mutually exclusive with the inventoryReferences field; if you populate this field, do not populate the inventoryReferences field.

A listing ID is the eBay listing identifier that's generated when the listing is created.

Note: This field accepts listingId values generated with both the Inventory API and the eBay Traditional APIs, such as the Trading and Finding APIs.

Maximum: 500 listings

Required if you do not supply an array of inventoryReferences values or if you set reportType to LISTING_PERFORMANCE_REPORT.

Occurrence: Conditional

marketplaceIdMarketplaceIdEnumThe ID for the eBay marketplace on which the report is based.

Maximum: 1

Required if reportType is set to ACCOUNT_PERFORMANCE_REPORT or INVENTORY_PERFORMANCE_REPORT.

Occurrence: Conditional

metricKeysarray of stringThe 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

reportFormatReportFormatEnumThe file format of the report. Currently, the only supported format is TSV_GZIP, which is a gzip file with tab separated values.

Occurrence: Required

reportTypeReportTypeEnumThe type of report to be generated, such as ACCOUNT_PERFORMANCE_REPORT, CAMPAIGN_PERFORMANCE_REPORT, and so on.

Maximum: 1

Occurrence: Required

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationThe URI of the report task, which includes the ID of the report task.

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

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.
POST
https://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"
POST
https://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"
POST
https://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.