Skip to main content

This archive document contains information about releases earlier than the previous ten versions. For current releases, see Marketing API release notes.

Release Version Release Date Description of Release
Version 1.15.2 2023-08-01 Promoted Listings: Added support for listing format as a criteria for Promoted Listings reporting.
Version 1.15.1 2023-05-04 Promoted Listings: Added new optional column to transaction report; removed support for multiple funding models from Promoted Listing Reports; added a new error code; removed support for deprecated TRANSACTION_REPORTmetricKeys.
Version 1.15.0 2023-03-15 Promoted Listings: Removed error message, added error messages, updated type description for bidPercentage, and increased days listed amount for DE, FR, IT, and ES
Version 1.14.0 2022-09-30 Promoted Listings: Added an error message, support for warning response headers, and deprecated capabilities information
Version 1.13.0 2022-07-13 Promoted Listings: Added support for campaigns that are not getting visibility due to a lower ad rate
Version 1.12.0 2022-07-11 Promoted Listings: Added a new updateAdRateStrategy method to the campaign resource, as well as new types to support this addition
Version 1.11.0 2022-07-11 Promoted Listings: Added support for the Promoted Listings Advanced (PLA) program, including new resources and several new methods
Version 1.10.2 2022-05-11 Promoted Listings: Increased the campaignIds limit for the createReportTask method
Version 1.10.1 2021-12-01 Promoted Listings: Added support for autoSelectFutureInventory in rules-based Promoted Listings campaigns, and added new error and warning messages to the createCampaign method
Version 1.10.0 2021-07-15 Promoted Listings: Added support for the Coded Coupon promotion type
Version 1.9.0 2021-07-12 Promoted Listings: The start and end times for Promoted Listings reports is standardized on UTC with local time zone offset
Version 1.8.0 2020-08-19 Promoted Listings:
  • 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 and 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.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.15.2

This release adds support for listing format as a criteria for Promoted Listings reporting.

Added new criteria to Promoted Listings reports

Promoted Listings reports now includes the dimensionKeylisting_format, which indicates if the listing was an auction or fixed price.

Version 1.15.1

This release removed support for multiple funding models from Promoted Listing Reports. To support this change, the following changes have been made.

Added new optional column to transaction report

For Promoted Listings, a column was added to the transaction report. This report now includes the optional dimensionKeysale_type which indicates if the transaction is a Halo Item or a Direct sale.

Removed support for deprecated TRANSACTION_REPORT metricKeys

Support has been removed for the following deprecated TRANSACTION_REPORTmetricKeys:

  • PLS Reports:
    • impressions
    • clicks
    • ctr
    • avg_cost_per_sale
    • pl_transactions
  • PLA Reports:
    • cpc_impressions
    • cpc_clicks
    • cpc_ctr
    • cpc_conversion_rate
    • cpc_return_on_ad_spend
    • cpc_avg_cost_per_sale
    • cpc_transactions
    • cpc_ad_fees_listingsite_currency
    • cpc_ad_fees_payout_currency
    • cost_per_click

New Error message

The following error code has been added to createReportTask:

  • 35124: Multiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}

Version 1.15.0

Removed error message, added error messages, updated type description for bidPercentage, and increased days listed amount for DE, FR, IT, and ES.

Error message changes

The following new error message was added to the bulkCreateAdsByInventoryReference, bulkCreateAdsByListingId, createAdByListingId, andcreateAdsByInventoryReferencemethods in this release:

Error/Warning Code Description
35010 The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign.

The following new error message was added to the bulkUpdateAdsBidByInventoryReference, bulkUpdateAdsBidByListingId, and updateBid methods in this release:

Error/Warning Code Description
35113 This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign.

The following error message was removed from the createCampaign and updateAdRateStrategy methods in this release:

Error/Warning Code Description
35112 The 'adRateAdjustmentPercent' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True.

Changed functionality

The bidPercentage request field in the FundingStrategy type has been updated in this release. Users should not provide a bidPercentage value when the adRateStrategy for the campaign is dynamic.

In the markdown promotion listing requirements, the Days Listed value has been updated from 14 to 30 days for the following markets:

  • DE
  • ES
  • IT
  • FR

Version 1.14.0

This release adds an error message, warning headers, and deprecates capabilities.

New error and warning messages

The following new error and warning message was added to the createReportTask, getReportTask, and getReportTasks methods in this release:

Error/Warning Code Description
35123 The 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel}

New HTTP response header

The following new HTTP response header was added to the createReportTask method in this release:

Header Meaning
Warning Carries additional information about the status or transformation of a message that might not be reflected in the status code.

API capabilities deprecated

The following list contains API capabilities that are deprecated and scheduled for decommission:

  • Multiple value support for the fundingModels array of the createReportTask method
  • Support for specific metric keys used in Transaction reports for either funding model: impressions, clicks, ctr, avg_cost_per_sale, pl_transactions, cpc_impressions, cpc_clicks, cpc_ctr, cpc_conversion_rate, cpc_return_on_ad_spend, cpc_avg_cost_per_sale, cpc_transactions, cpc_ad_fees_listingsite_currency, cpc_ad_fees_payout_currency, cost_per_click.

See API Deprecation Status for additional details.

Version 1.13.0

This release adds support for campaigns that are not getting visibility due to a lower ad rate.

Schema changes

The ad and campaign resources now include the alerts container field, its types, and new enumerated values of AspectKeyEnum, AlertTypeEnum, and DimensionKeyEnum. The following new types were added:

Version 1.12.0

This release adds a new method and new types to support the Promoted Listings Standard (PLS) program.

Schema changes

The campaign resource now includes the new updateAdRateStrategy method. This method updates the ad rate strategy for an existing PLS rules-based ad campaign that uses the Cost Per Sale (CPS) funding model.

Note: This new method is not applicable for Promoted Listings Advanced (PLA) campaigns that use the Cost Per Click (CPC) funding model.

In addition to the new method, the following new types were added in this release:

Version 1.11.0

This release adds new resources and methods to support the Promoted Listings Advanced (PLA) program, along with updates to the existing schema to support these additions.

Note: The PLA program is only available to developers and applications that have been approved by eBay.

Schema changes

The following new methods were added in this release to support the PLA program:

Tip: For more information about how these new methods are used to create and maintain PLA ad campaigns, see the Promoted Listings playbook in the Selling Integration Guide.

Version 1.10.2

This release increases the number of campaigns that can be included in Promoted Listings reports.

Changed functionality

The campaignIds request field in the createReportTask method has been updated in this release. Users can now specify up to 25 campaigns in a request to create a report task.

Version 1.10.1

In this release, support was added for autoSelectFutureInventory in rules-based Promoted Listings campaigns, as described in the sections that follow.

Changed functionality

The existing autoSelectFutureInventory request field in the createCampaign method, previously reserved for future use, is now supported for use in rules-based Promoted Listings campaigns.

This request field can be used to indicate whether listings shall be automatically added to, or removed from, a Promoted Listings campaign, according to the rules that have been set. If set to true, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory.

New error and warning messages

The following new error and warning messages were added to the createCampaign method in this release:

Error/Warning Code Description
35103 This campaign has reached maximum capacity of {maxSupportedNumber} listings. To continue promoting listings, create a new campaign.
35104 'categoryScope' STORE can not be found. Please define the store categories first or use 'categoryScope' MARKETPLACE to select categories.

Version 1.10.0

This release adds support for the Coded Coupon promotion type.

Changed functionality

A Coded Coupon is a unique code that buyers can use during checkout to receive a discount. The code may be private, appearing only on the seller's Offer page, or it may be made public, appearing on the Offer page, the search results page, the View Item page, and the Checkout page. The seller may limit the number of times a buyer can use the coupon code and can set a budget that defines the maximum total cumulative amount that can be discounted from all uses of the coupon code.

Version 1.9.0

This release updates the start and end time inputs used for Promoted Listings reports.

Changed functionality

With this release, Promoted Listings report start and end times are no longer synchronized according to Mountain Standard Time (MST).

The dateFrom and dateTo request fields for all Promoted Listing reports are now input as ISO 8601-formatted strings, which are based on the 24-hour Coordinated Universal Time (UTC) clock with local offset.

For example, if a user wanted to create a report task based on the MST time zone, the timestamp would be input as follows (MST = UTC - 7 hours):

2021-03-15T13:00:00-07:00

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.

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.

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.

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.

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

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.

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

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:

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

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.