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
- Marketing API Reference
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.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.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.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:
impressionsclicksctravg_cost_per_salepl_transactions
- PLA Reports:
cpc_impressionscpc_clickscpc_ctrcpc_conversion_ratecpc_return_on_ad_spendcpc_avg_cost_per_salecpc_transactionscpc_ad_fees_listingsite_currencycpc_ad_fees_payout_currencycost_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:
- ad (existing resource):
- ad_group (new resource):
- campaign (existing resource):
- keyword (new resource):
- negative_keyword (new resource):
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