Just getting started with the Marketing API? See the following documents for details on using this API:

Announcements

See the API Status page 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. For older releases, see the Marketing API release notes archive.

Version Release Date Summary of Release
Version 1.19.0 2023-11-09 Promoted Listings Advanced: Dynamic Bidding has been added to Cost per Click (CPC) campaigns.
Version 1.18.0 2023-10-11 Promoted Listings: Add support for Offsite Ads campaigns, including new fields and a new method.
Version 1.17.2 2023-09-25 Increased the maximum number of campaignIds for PLS from 25 to 1,000. Increased the data threshold for a report from 200,000 to 500,000.
Version 1.17.1 2023-09-22 Added new error code 35130 to method createReportTask and added new annotation key target_type for campaign_id that will be supported for COST_PER_CLICK funding model.
Version 1.17.0 2023-08-17 Added new email_campaign methods to support new features for Store Email Campaigns.
Version 1.16.0 2023-08-15 Promoted Listings: Added two new methods, quickSetupCampaign and LaunchCampaign, to support quick setup PLA campaign functionality.
Version 1.15.3 2023-08-07 Promoted Listings Standard: Standard campaigns can now be applied to auction listings on eBay Germany marketplace.
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_REPORT metricKeys.
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.19.0

This release adds support for Dynamic Bidding to Cost per Click (CPC) campaigns.

New method

The following new method has been added to the campaign resource to support Dynamic Bidding campaigns:

  • updateBiddingStrategy: This method allows sellers to change the bidding strategy for a specified Cost Per Click (CPC) campaign.

Schema changes

The following schema changes have been made to support Dynamic Bidding campaigns:

  • New enumerated value BiddingStrategyEnum has been added to the following methods:

    • cloneCampaign
    • createCampaign
    • findCampaignByAdReference
    • getCampaign
    • getCampaignByName
    • getCampaigns
  • New biddingStrategy field has been added to the FundingStrategy type.

Errors, warnings, and statuses

The following error has been added to the createCampaign method:

  • 35132: The 'biddingStrategy' field is not supported for CPS funding model.

The following warning has been added to the bulkCreateKeyword, bulkUpdateKeyword, createKeyword, and updateKeyword methods:

  • 35133: The bid provided in the call was ignored because the selected biddingStrategy is DYNAMIC for the campaign.

The following status has been added to the updateKeyword method:

  • 200: Success

Version 1.18.0

This release adds updates to the existing schema and a new methods to support Offsite Ads campaigns, as well as adds new error messages for this new functionality.

Changed Functionality:

Using the createCampaign method, sellers can now create an Offsite Ads campaign by setting the new channels array to OFF_SITE in the request. An Offsite Ads campaign allows sellers to create their own advertising campaign and promote their listings on leading external channels.

Sellers can also now use the createReportTask method to monitor their Offsite ads campaigns by passing the channels array with the value of OFF_SITE.

Schema changes

The createCampaign, createReportTask, getCampaign, and getCampaigns methods now include the channels array and the new enumerated value of ChannelEnum.

New Method

The following method has been added as a part of the campaign resource to support Offsite Ads campaigns:

  • suggestBudget: This method allows sellers to retrieve the suggested budget for an Offsite Ads campaign.

New Error Messages

The following error messages have been added to the createReportTask method: 

Error/Warning Code Description
35125 The 'channel' is invalid. Valid values are: {supportedChannels}
35126 Multiple channels are not supported. Please use one of the following channels: {supportedChannels}
35127 The 'channels' are not supported for the 'fundingModel' {fundingModel}
25128 The 'dimensionKey' {dimensionKey} is not valid for the 'channels' {supportedChannels}
35129 The 'metricKey' {metricKey} is not valid for the 'channels' {supportedChannels}
35131 The 'annotationKey' {annotationKey} is not supported for the 'channels' {supportedChannels}

The following error messages have been added to the createCampaign method:

Error/Warning Code Description
35094 Maximum number of campaigns allowed with the 'channels' value {channel} is exceeded.
35095 'marketplaceId' {marketplaceId} is not supported. Offsite Ads is supported only on these marketplaces: {supportedMarketplaces}.
36406 The 'channels' value {channel} can only be used with the {funding_model} fundingModel.
36407 The 'channels' value is invalid.

The following error message has been added to the updateCampaignBudget method:

Error/Warning Code Description
36408 The seller must accept the new pricing policy before the campaign can be updated.

The following error message has been added to the updateCampaignIdentification method:

Error/Warning Code Description
36408 The seller must accept the new pricing policy before the campaign can be updated

Version 1.17.2

Increased the maximum number of campaignIds for PLS from 25 to 1,000.

The data threshold for a single report has been increased from 200,000 to 500,000.

Version 1.17.1

Added new error code 35130 to method createReportTask and added new annotation key target_type for campaign_id that will be supported for COST_PER_CLICK funding model.

Version 1.17.0

This release added 8 new email_campaign methods that allow users to create and send email campaigns to customers who have signed up to receive a seller's newsletter.

New Methods

The following methods have been added as part of the email_campaign resource: 

  • createEmailCampaign: This method can be used to create any of the available email campaign types.

  • updateEmailCampaign: This method can be used to make changes to an existing email campaign.

  • deleteEmailCampaign: This method can be used to delete one email campaign at a time.

  • getEmailCampaign: This method returns the details of a single email campaign.

  • getEmailCampaigns: This method retrieves a seller's email campaigns.

  • getAudiences: This method returns the details on the available audiences for a particular email campaign type.

  • getEmailPreview: This method returns a preview of the contents of an email campaign.

  • getEmailReport: This method returns data on user engagement for a seller's email campaign.

Version 1.16.0

This release adds two new methods to the campaign resource of the Marketing API: setupQuickCampaign and launchCampaign.

These new methods support quick setup Promoted Listings Advanced Campaign creation, providing sellers with an easier PLA campaign setup experience.

New Methods

The following methods have been added to the campaign resource of the Marketing API to support quick setup Promoted Listings Advanced (PLA) campaign functionality: 

  • setupQuickCampaign: This method allows the seller to expedite the creation of a PLA campaign, providing an easy campaign setup experience for sellers. Sellers only need to provide basic campaign information and eBay creates ad groups and keywords for the campaign.

  • launchCampaign: This method launches a PLA campaign that has been created using the setupQuickCampaign method.

Version 1.15.3

Promoted Listings Standard campaigns can now be applied to auction listings on eBay Germany marketplace. No schema updates were required for this enhancement.

Added new items to Promoted Listings listing Requirements

The following items were added:

  • For Promoted Listings Standard, the eBay Germany marketplace supports both fixed-price listings and auction listings with Buy It Now feature enabled. All other eBay marketplaces only support fixed-price listings for Promoted Listings Standard.

  • For Promoted Listings Advanced, the item must be a fixed price (Buy It Now) item.

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 dimensionKey listing_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 dimensionKey sale_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_REPORT metricKeys:

  • 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