Just getting started with the Marketing API? See the following documents for details on using this API:
- Using eBay RESTful APIs
- Marketing section of the Selling Integration Guide
- Marketing API Overview
- Marketing API Reference
Announcements
See the API Site Status for announcements regarding current and recently resolved system wide issues. Visit the Developer Support page for support options and information on filing bugs.
The API release history
The following table lists the releases for the Marketing API:
Version |
Release Date |
Summary of Release |
---|---|---|
2018-05-11 |
Promotions Manager: Added the item_price_markdown resource and four associated methods to support markdown promotions. Promoted Listings: The maximum value allowed for bidPercentage was raised from 20% to 100%. |
|
2017-05-31 |
Version 1.3.0 contains the following updates:
|
|
2017-04-26 |
Added methods to support new reporting features for Promoted Listings. |
|
Version 1.1.0 |
2017-03-07 |
Added a new method that returns the listings associated promotions created with Promotions Manager. Added a container to support creating threshold promotions using a set of rules. |
Version 1.0.0 |
2016-10-19 |
Initial release of Version 1. |
Version 1.4.0
This release adds several new methods to the Marketing API, plus one schema change to support item price markdown promotions.
New methods
A new resource (item_price_markdown) and several methods have been added to the Marketing API. Item price markdown promotions are available in all eBay marketplaces.
Here is the list of the methods that were added to support item price markdown promotions:
- createItemPriceMarkdownPromotion =
POST /item_price_markdown
Creates a markdown promotion. - deleteItemPriceMarkdownPromotion =
DELETE /item_price_markdown/{promotion_id}
Deletes a markdown promotion by ID. - getItemPriceMarkdownPromotion =
GET /item_price_markdown/{promotion_id}
Retrieves a markdown promotion by ID. - updateItemPriceMarkdownPromotion =
PUT /item_price_markdown/{promotion_id}
Updates a markdown promotion by ID.
Schema changes
There is a single schema change to support the new item price markdown promotions:
- A new query parameter, status, has been added to getListingSet to filter the promotions returned by their status. This parameter is valid for only markdown promotions.
Changed functionality
The Marketing API v1.4.0 release includes the following functionality changes:
- In Promoted Listings, the maximum value that you can specify for bidPercentage was raised from 20% to 100%.
- In Promotions Manager, the maximum number of inventory items or listing IDs that you can include in a promotion has been increased from 500 items to 2,000 items. These increases are reflected in the inventoryItems and listingIds fields in the inventoryCriterion container.
Documentation changes and errata
This version of the API documentation formally introduces Promotions Manager as a product. In previous versions of the documentation, Promotions Manager had only a single set of functions, all of which supported item promotions.
Version 1.4.0 introduces "item price markdown promotions" and these, along with item promotions, are grouped under the Promotions Manager umbrella. For ease of reference, item promotions are nicknamed threshold promotions and item price markdown promotions are simply called markdown promotions.
Version 1.3.0
The following sections detail the updates that have been made for this release:
New methods
The following methods was added in this release:
- getPromotionReports =
GET /promotion_report
This call generates a report for all the seller'sRUNNING
,PAUSED
, orENDED
promotions for the specified eBay marketplace. It summarizes the seller's performance at a promotion level on a given site. You must specify the eBay marketplace and can limit the report by using a search keyword or by specifying the promotion status to include. You can also control the number of promotions returned in the result set.
Schema changes
Several errors were changed to warnings in the createItemPromotion and updateItemPromotion methods:
Code |
Category |
Nature |
Meaning |
---|---|---|---|
38226 | REQUEST | WARNING | The listing ID must be numeric if you're using listingIds. |
38227 | REQUEST | WARNING | The listing ID is invalid. |
38263 | REQUEST | WARNING | The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}. |
38272 | BUSINESS | WARNING | This listing is not eligible for a promotion because it's an auction-style listing. |
38273 | BUSINESS | WARNING | This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing. |
38274 | BUSINESS | WARNING | You haven't included PayPal as a payment method. In order to make this listing eligible, update it to include PayPal. |
38275 | BUSINESS | WARNING | This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label). |
345112 | REQUEST | WARNING | Invalid Store category. Please refer to API documentation to source allowed values. |
345113 | REQUEST | WARNING | Invalid Marketplace Category ID. Please refer to API documentation to source allowed values. |
Documentation changes and errata
Information was added on how to use the Taxonomy API to retrieve category IDs.
Although the list of eBay category IDs is not published, you can use the Taxonomy API to retrieve the default category tree for a seller's marketplace. The Taxonomy API provides calls that enable the seller to browse or search the category tree hierarchy and select categories to use as criteria for the promotion. See the Taxonomy API.
Version 1.2.0
This release adds several new methods to the Marketing API.
New methods
The following report-related methods have been added to Promoted Listings:
- getReport =
GET /ad_report/{report_id}
Downloads a Promoted Listings report by ID. - getReportMetadata =
GET /ad_report_metadata
Retrieves metadata that details the fields returned in all Promoted Listings reports. - getReportMetadataForReportType =
GET /ad_report_metadata/{report_type}
Retrieves metadata that details the fields returned in a specific Promoted Listings report. - createReportTask =
POST /ad_report_task
Creates a report task, which generates a Promoted Listings report. - deleteReportTask =
DELETE /ad_report_task/{report_task_id}
Deletes a Promoted Listings report task and any associated reports by ID. - getReportTask =
GET /ad_report_task/{report_task_id}
Retrieves the details on a Promoted Listings report task by ID. - getReportTasks =
GET /ad_report_task
Retrieves a detailed list of the seller's report tasks. You can filter and paginate the result set.
Version 1.1.0
The following sections detail the updates that have been made for this release.
New methods
This release added one new method:
- getListingSet =
GET /promotion/{promotion_id}/get_listing_set
This method returns a paginated result set of the listings associated with the specified promotion that was created with Promotions Manager.
Schema changes
The following changes were made to the schema:
Added new inventoryCriterion.ruleCriteria container
The inventoryCriterion.ruleCriteria container was added to the createItemPromotion, getItemPromotion, and updateItemPromotion calls. This enables sellers to select the listings to include in the promotions created with Promotions Manager by using a set of rules such as a list of eBay or seller's Store category IDs, items constrained by minimum and maximum prices, and the item brand or condition. You can explicitly exclude up to 100 eBay listing IDs or seller inventory reference IDs (also known as an SKU or custom label). Also, a single promotion can have multiple rules.
Documentation changes and errata
More examples were added to the Configuring discounts for threshold promotions topic.
Version 1.0.0
This is the initial release of the Marketing API, Version 1.
For a list of methods, see the Marketing API Reference.