Marketing API release notes

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
    Promoted Listings requirements and restrictions
    Promotions Manager requirements and restrictions
• 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
Version 1.8.0	2020-08-19	Added new error message 35078. Updated the description of error message 35077. Added a new status to CampaignStatusEnum.
Version 1.7.0	2020-02-28	Promoted Listings: Increased the maximum amount of listings per campaign from 25,000 to 50,000 and added support for Promoted Listings methods to the following eBay marketplaces: Canada (English) Canada (French) France Italy Spain
Version 1.6.0	2019-09-11	Promoted Listings: The start and end times for Promoted Listings reports is standardized on MST.
Version 1.5.0	2019-04-30	Promotions Manager: Added volume pricing to item_promotion resource and added two new fields to address the increased functionality.
Version 1.4.0	2018-05-11	Promotions Manager: Added the item_price_markdown resource and four associated methods to support markdown promotions. Increased the maximum number of items in a promotion from 500 to 2,000. Promoted Listings: The maximum value allowed for bidPercentage was raised from 20% to 100%.
Version 1.3.0	2017-05-31	Version 1.3.0 contains the following updates: Added new Promotion report methods Changed some errors to warnings Added information about how to use the Taxonomy API to retrieve category IDs.
Version 1.2.0	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.8.0

In this release, the error message text for error code 35077 has been modified, and the new error code 35078 has been added. A new status for the CampaignStatusEnum enumerated values, SYSTEM_PAUSED, has also been added.

v1.8.0: Error message updates

Error Code	Description
35077	To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.
35078	To gain access to Promoted Listings, you must be in good standing with recent sales activity.

The previous error code 35077 required that sellers had to own an eBay store to use Promoted Listings. The new error message removes that requirement.

v1.8.0: New CampaignStatusEnum value

A new enumerated value and description have been added to CampaignStatusEnum. The new value is SYSTEM_PAUSED. This status indicates a system-generated, temporary pause on the campaign due to the seller's level dropping to Below Standard. Below Standard sellers cannot create new campaigns or edit their existing campaigns, but they can still view their campaign data and download reports. Once their seller level improves to Above Standard or Top Rated, sellers can resume using Promoted Listings and their campaigns will be automatically unpaused and return their last status.

Version 1.7.0

This release increases the maximum amount of listings per campaign and adds Promoted Listings support for new eBay marketplaces.

v1.7.0: Changed functionality

This release includes the following Promoted Listings functionality changes:

• The maximum amount of listings per campaign has increased from 25,000 to 50,000.
• The Promoted Listings methods are now supported for the following eBay marketplaces:
  • Canada (English)
  • Canada (French)
  • France
  • Italy
  • Spain

The table below lists the links to terms and conditions for all marketplaces that support Promoted Listings:

Marketplace	Promoted Listings Terms and Conditions URL
Australia	https://scgi.ebay.com.au/ws/ebayisapi.dll?useragreementv2&agrid=17
Canada (English)	https://scgi.ebay.ca/ws/ebayisapi.dll?useragreementv2&agrid=17
Canada (French)	https://scgi.cafr.ebay.ca/ws/ebayisapi.dll?useragreementv2&agrid=17
France	https://scgi.ebay.fr/ws/ebayisapi.dll?useragreementv2&agrid=17
Germany	https://scgi.ebay.de/ws/ebayisapi.dll?useragreementv2&agrid=17
Italy	https://scgi.ebay.it/ws/ebayisapi.dll?useragreementv2&agrid=17
Spain	https://scgi.ebay.es/ws/ebayisapi.dll?useragreementv2&agrid=17
United Kingdom	https://scgi.ebay.co.uk/ws/eBayISAPI.dll?useragreementv2&agrid=17
United States	https://scgi.ebay.com/ws/eBayISAPI.dll?useragreementv2&agrid=17&guest=1

Version 1.6.0

This release standardizes the start and end times used for Promoted Listings reports.

v1.6.0: Changed functionality

This release synchronizes Promoted Listings report start and end times with Mountain Standard Time (MST).

Promoted Listings reports are aggregated on a daily basis where each reporting day begins at midnight. With this release, the start time and end time for all Promoted Listing reports is synchronized with MST, which is calculated by subtracting seven hours from the Coordinated Universal Time (UTC). In other way, all Promoted Listings reports start and end at midnight, on the specified dates, based on Mountain Standard Time.

Version 1.5.0

This release adds volume pricing functionality to the item_promotions methods, plus some updates to the Promotions Manager functionality:

• Schema changes
• Changed functionality

v1.5.0: Schema changes

Volume pricing has been added as a new type of promotion you can create with the Promotions Manager item_promotion resource. Volume pricing gives you the ability to give buyers deeper discounts as they purchase higher quantities of items from your store.

With this release, volume pricing is supported on all the marketplaces on which Promotions Manager is supported by the API (EBAY_AU, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_IT, EBAY_GB, EBAY_US). Volume pricing can be added to both single variation and mult-variation fixed price listings on all supported marketplaces.

To support volume pricing, the item_promotion resource has been updated in the following ways:

• promotionType has been added for use with both item_promotion and item_price markdown resources.
• The promotionType field supports the following enumeration values: VOLUME_DISCOUNT, ORDER_DISCOUNT, and MARKDOWN_SALE.
• While promotionType is optional for ORDER_DISCOUNT and MARKDOWN_SALE promotions, you must include the promotionType field in your requests to create volume pricing promotions.
• The applyDiscountToSingleItemOnly Boolean flag has been added to the ItemPromotion type. Evaluated only for volume pricing promotions, this flag indicates if the promotion applies to just a single item in the set of items being promoted, or if the discount applies across any of the items being promoted in the seller's Store.

v1.5.0: Changed functionality

This release includes the following Promotions Manager functionality changes:

• For Promotions Manager:

  • The requirements for creating promotions have been relaxed in that you no longer need to opt-in to a Promotions Manager program to create threshold or markdown promotions.
  • The listing requirements for markdown promotions have been refined. For full details, see Promotions Manager requirements and restrictions.
  • The allowed values for amountOffItem have been expanded for markdown promotions, as detailed here: amountOffItem.

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
• Schema changes
• Changed functionality
• Documentation changes and errata

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

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

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

v1.4.0: Documentation changes and errata

This version of the API documentation formally introduces Promotions Manager as a product, and identifies two flavors of promotions: markdown promotions and threshold promotions. In previous versions of the documentation, Promotions Manager had only a single set of functions, all of which supported threshold promotions with the item_promotion resource.

Version 1.4.0 introduces "item price markdown promotions" and these, along with threshold promotions, are grouped under the Promotions Manager umbrella.

Version 1.3.0

The following sections detail the updates that have been made for this release:

• New methods
• Schema changes
• Documentation changes and errata

v1.3.0: New methods

The following method was added in this release:

• getPromotionReports = GET /promotion_report
  This call generates a report for all the seller's RUNNING, PAUSED, or ENDED 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.
  

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

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

v1.2.0: 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
• Schema changes
• Documentation changes and errata

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 resources and methods, see the Marketing API Reference.