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.21.0 2024-03-28Promoted Listings Advanced: Added support for smart targeting PLA campaigns
Version 1.20.0 2023-12-15 New URI parameters, Response field, HTTP Status Code and Error Codes have been added to getReportMetadata and getReportMetadataForReportType methods and samples have been updated.
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, setupQuickCampaign 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.21.0

This release adds updates to the existing schema to support smart targeting for Promoted Listings Advanced (PLA) campaigns, as well as adds new error messages for this functionality.

Changed Functionality

Using the createCampaign method, sellers can now create smart targeting PLA campaigns by setting the campaignTargetingType to SMART and specifying the max cost per click they are willing to pay through the maxCpc field. Smart targeting campaigns are easy to set up and automatically optimize ad campaign settings and handle the bidding and targeting for the seller.

Sellers can update the maxCpc of their smart targeting campaign through the updateBiddingStrategy method.

Schema Changes

The following fields have been added to the createCampaign, getCampaign, getCampaignByName, and getCampaigns methods:

  • campaignTargetingType

  • bidPreferences

  • maxCPC

The following fields have been added to the updateBiddingStrategy method:

  • bidPreferences

  • maxCPC

New Error Codes

The following error code has been added to the createAdGroup, getAdGroups, getAdGroup, updateAdGroup, suggestBids, suggestKeywords, createKeyword, bulkCreateKeyword, updateKeyword, bulkUpdateKeyword, createNegativeKeyword, bulkCreateNegativeKeyword, updateNegativeKeyword, bulkUpdateNegativeKeyword methods: 

Error Code Description
35129 This method is not supported for campaigns with smart targeting type

The following error codes have been added to the bulkCreateAdsByListingId method: 

Error Code Description
35064 This operation is only supported for key based campaigns
35068 You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call
36412 Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again.

The following error code has been added to the createAdsByListingId, getAds, bulkUpdateAdsByListingId, bulkCreateAdsByListingId, bulkUpdateAdsStatusByListingId methods: 

Error Code Description
36412 Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again.

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

Error Code Description
35124 The 'maxCpc' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}.
35127 'maxCPC' is only supported for CPC funding model campaigns with on-site channels and smart targeting type.
35128 'campaignTargetingType' is only supported for CPC funding model campaigns with on-site channels.

The following error codes have been added to the updateBiddingStrategy method: 

Error Code Description
35124 The 'maxCpc' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}.
35126 The 'biddingStrategy' isn't applicable for campaigns with smart targeting type.
35127 'maxCPC' is only supported for CPC funding model campaigns with on-site channels and smart targeting type.

Version 1.20.0

This release adds new URI parameters, response field, HTTP Status Codes and Error Codes to getReportMetadata and getReportMetadataForReportType methods and corresponding samples have been updated.

The following URI parameters are added to getReportMetadata and getReportMetadataForReportType methods.

  • funding_model
  • channel

The following response field is added to ReportMetadata type

  • channel

The following HTTP Status Code is added to getReportMetadata and getReportMetadataForReportType methods.

  • 400 - Bad Request

The following Error Codes are added to getReportMetadata and getReportMetadataForReportType methods.

  • 35121 - The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}.
  • 35125 - The 'channel' is invalid. Valid values are: {supportedChannels}.
  • 35127 - The 'channels' are not supported for the 'fundingModel' {fundingModel}.

The following Error Codes are added to getReportMetadataForReportType method.

  • 35132 - The 'channels' {supportedChannels} are not supported for the 'report_type' {reportType}.
  • 35133 - The 'fundingModel' is not supported for the 'report_type' {reportType}.

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