Skip to main content

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.22.0 2024-07-16 Priority strategy campaign: Added new suggestMaxCpc method
Version 1.21.2 2024-04-29 Promoted Listings Standard: Added support for auction listings for PLS campaigns on all marketplaces.
Version 1.21.1 2024-04-25

Promoted Listings Advanced: Added new campaign_targeting_types filter for getCampaigns and added new error codes for createCampaign and updateBiddingStrategy.

Version 1.21.0 2024-03-28 Promoted 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.22.0

This release adds the suggestMaxCpc method to the campaign resource. This method allows sellers to retrieve the suggested maxCpc value for a smart targeting priority strategy campaign.

Version 1.21.2

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

Updated Promoted Listings Standard listing Requirements

For Promoted Listings Standard, all marketplaces now support fixed-price listings, auction listings, and auction listings with Buy It Now feature enabled.

Version 1.21.1

This release adds a new filter option to the getCampaigns method, as well as various new error codes relating to smart targeting campaigns for createCampaign and updateBiddingStrategy.

Added new filter to getCampaigns

The optional campaign_targeting_types filter has been added to the getCampaigns method. This new query parameter allows users to filter their results by campaign targeting type, such as only returning smart targeting campaigns.

New error codes

The following error code has been added to getCampaigns:

Error Code Description
35123 The 'campaignTargetingType' is not valid. Valid values for 'campaignTargetingType' are: {campaignTargetingTypeValues}.

The following error codes have been added to createCampaign and updateBiddingStrategy:

Error Code Description
35125 The 'bidPreferences' list currently supports only one element. Please remove additional elements and try again.
35134 A 'biddingStrategy' cannot be supplied for smart targeting campaigns. Please either remove 'biddingStrategy' from the request to create a smart targeting campaign or supply another value for 'campaignTargetingType'.
36161 Smart targeting campaigns require a 'bidPreferences.maxCpc' value.
36162 The 'maxCpc' currency should be the same as the daily budget.
36163 The 'maxCpc' value {maxCpcValue} is below minimum value {maxCpcMinimumValue}.
36164 The 'maxCpc' value {maxCpcValue} is above maximum value {maxCpcMaximumValue}.
36165 The 'maxCpc' value {maxCpcValue} is more than maximum daily budget {maxDailyBudget}.
36166 The 'maxCpc' value {maxCpcValue} is invalid. Refer to the API call documentation for more information.

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.

Got thoughts? Click the feedback button – your insights help us improve!