Skip to main content

The Marketing API supports three eBay marketing features - Promoted Listings, Promotions Manager, and Store Email Campaigns. Used separately or together, these three marketing features can increase views and sales of the seller's items.

Promoted Listings is an eBay advertising service that increases the visibility of items included in a seller's ad campaigns. For more information on Promoted Listings, see the Promoted Listings Playbook.

Promotions Manager is a free service that gives sellers the ability to offer price discounts on their items. For more information on Promotions Manager, see the Promotions Manager section of the Selling Integration Guide.

Email Store Campaigns allow eBay store sellers to create and send email campaigns to subscribers, followers, and past customers who’ve signed up to receive newsletters from a seller’s store. For more information on email campaigns, see the Store Email Campaigns section of the Selling Integration Guide.

Note: The Marketing API works with listings that have been created with the Trading API as well as listings that are managed with the Inventory API.

Promoted Listings

Promoted Listings allow sellers to create advertising campaigns to promote their products. Promoted Listings campaigns have three main campaign types:

  • Promoted Listings Standard (PLS), which uses the Cost Per Sale (CPS) funding model

  • Promoted Listings Advanced (PLA), which uses the Cost Per Click (CPC) funding model

  • Offsite Ads, which allows sellers to promote their eBay listings on external search channels

For more information on Promoted Listings campaign types, see the Promoted Listings Playbook.

Promoted Listings technical overview

The resources applicable to both PLS and PLA campaigns are listed below:

  • ad – Add listings, either individually or in bulk, to existing campaigns (CPS) or ad groups (CPC). You can also retrieve a list of existing campaign ads. For the CPS model, you can update bid percentages. For the CPC model, you can pause, resume, or archive ads using this resource.

  • campaign – Create and manage campaigns with the methods in this resource.

  • ad_report – Retrieve a completed Promoted Listings report with the getReport method.

  • ad_report_metadata – Get metadata about the fields that are required and optional for the different types of Promoted Listings reports. This metadata can help you create a report task.

  • ad_report_task – Create report tasks that initiate the generation of a Promoted Listings report. There is also a method to delete report tasks.

The resources applicable only to manual targeting PLA campaigns are listed below:

  • ad_group – An ad group is associated with a campaign that uses the CPC funding model. You can add one or more ad groups per campaign. You can also get a list of existing ad groups in a campaign and pause, resume, or archive ad groups using this resource.

  • keyword – In the CPC funding model, you can bid on keywords to use for the ad group in your Promoted Listings Advanced campaigns. You can also get a list of existing keywords with their bids, and pause, resume, or archive keywords using this resource.

  • negative_keyword – In the CPC funding model, you can create negative keywords for ad groups in your Promoted Listings Advanced campaigns. Negative keywords help prevent your Promoted Listings Advanced campaigns from surfacing unnecessarily when buyers run keyword searches that do not apply to your listings. You can also retrieve a list of existing negative keywords, or update the statuses of existing negative keywords using this resource.

Promoted Listings use cases

The following use cases outline the high-level ways that sellers can take advantage of Promoted Listings.

Create a PLS campaign

Promoted Listings Standard (PLS) campaigns offer sellers a simple and straightforward way to set up and manage their advertising campaign. PLS campaigns use the Cost-Per-Sale funding model, meaning a seller is only charged when a buyer clicks on their promoted listed ad and purchases the promoted items within 30 days. The amount they are charged per sale is determined by the ad rate of the campaign, which is the percentage of the item’s sale price.

To create a campaign, sellers can use the createCampaign method. To specify the campaign as a PLS campaign, the fundingModel field must be set to COST_PER_SALE and the ad rate must be specified through the bidPercentage field.

For more information about creating a PLS campaign, see Promoted listings standard campaign creation flow.

Create a PLA campaign

Promoted Listings Advanced (PLA) campaigns offer sellers more control over their campaign through suggested bids, keywords, and ad groups. PLA campaigns use the Cost-Per-Click funding model, meaning a seller is charged each time a buyer clicks on their promoted listings ad.

To create a campaign, sellers can use the createCampaign method. To specify the campaign as a PLA campaign, the fundingModel must be set to COST_PER_CLICK and the daily budget for the campaign must be set through the budget field.

There are two types of PLA campaigns: manual targeting and smart targeting. Details on each are shown below.

Create a manual targeting PLA campaign

Manual targeting campaigns give sellers control over campaign setup for ads that appear across eBay, allowing them to manually create and manage all aspects of their campaign. With manual targeting, sellers sort listings into ad groups, allowing them to target buyers with focused keywords and improve the visibility of their listings.

Manual targeting campaigns can be created in two different ways: manual setup or quick setup.

Manual setup gives sellers complete control over the creation of their PLA campaign through the createCampaign method. Sellers are able to manually add listings to ad groups, create keywords, and set keyword bids to help their listings reach their intended audience. To manually create a manual targeting campaign, set the campaignTargetingType enum to MANUAL during the createCampaign process. After a campaign has been created, sellers can utilize the various methods of the Marketing API, such as createAdGroup and createKeyword, to manage their campaign.

Alternatively, sellers can use the setupQuickCampaign method to expedite the creation of a Promoted Listings Advanced (PLA) campaign. Sellers only need to provide basic campaign information, such as the campaign name, duration, marketplace, daily budget amount, and associated listing ids. Using the provided listing ids, eBay creates ad groups for the campaign and organizes the listings into the appropriate ad group. eBay then adds keywords to each ad group and assigns each keyword to a suggested bid. Once a seller has reviewed and approved the draft of the campaign, they can use the launchCampaign method to launch, or schedule to launch, the campaign.

For more information on manual targeting PLA campaigns, see Manual targeting campaigns.

Create a smart targeting PLA campaign

Smart targeting ad campaigns automatically update over time to optimize campaign settings. Sellers can select the listings they would like to promote, and eBay will take care of bidding and targeting.

Sellers can set up Smart Targeting by using the createCampaign method. To do so, campaignTargetType must be passed as SMART, and the maximum amount the seller is willing to pay for each click on their ad must be specified through the maxCpc field of the bidPreferences container.

Note: Smart Targeting is only available for on-site PLA campaigns.

For more information, see Smart targeting campaigns .

Create an Offsite Ads campaign

Offsite Ads campaigns allow sellers to create their own advertising campaign and promote their eBay listings in external search channels, reaching new buyers and driving increased traffic to their listings.

Sellers can use the createCampaign method to create an Offsite Ads campaign. To do so, the fundingModel field must be passed as COST_PER_CLICK and the channels array must be passed as OFF_SITE. Sellers can also use the suggestBudget method, which is only applicable for Offsite Ads campaigns, to retrieve the suggested budget for the campaign.

For more information on creating and managing Offsite Ads campaigns, see the Offsite Ads.

Note: Offsite Ads is only available for campaigns that use the Cost Per Click (CPC) funding model. Use the getAdvertisingEligibility method of the Account API v1 to determine your eligibility status for eBay advertising programs.

Create reports on the performance of your Promoted Listings campaigns

Promoted Listings includes a reporting service that lets you create five different types of reports that gives sellers different views of how their promotions are performing. For details, see Promoted Listings reporting.

For more information, see Smart targeting campaigns .

Promoted Listings requirements and restrictions

This section details the requirement and restrictions pertaining to Promoted Listings campaigns.

Supported marketplaces and seller requirements

Before a seller can create a Promoted Listings campaign, they must be authorized by eBay, as well as accept the terms and conditions for the marketplace on which they want to create a Promoted Listings campaign.

The table below lists the supported marketplaces for each Promoted Listings campaign type, as well as the links to the terms and conditions for each marketplace:

Marketplace Funding Model Promoted Listings Terms and Conditions URL
Australia CPS and CPC
Canada (English) CPS and CPC
Canada (French) CPS and CPC
France CPS and CPC
Germany CPS and CPC
Italy CPS and CPC
Spain CPS
United Kingdom CPS and CPC
United States CPS and CPC

Promoted Listings listing requirements

Before an item can be added to a Promoted Listings campaign, it must meet the following listing requirements:

  • For Promoted Listings Standard, the following listing formats are supported: 

    • Fixed price

    • Auction

    • Auction Buy It Now

  • For Promoted Listings Advanced, only fixed-price listings are supported.

  • The item must be in one of the Promoted Listings supported categories. The following categories are not supported for Promoted Listings:

    • Wholesale & Job Lots

    • Cars, Motorcycles & Vehicles

    • Event Tickets

    • Property

    • E-Cigarettes, Vapes & Accs

    • Everything Else

Note: The Sandbox does not have all the functionality needed to do end-to-end testing on the Promoted Listings service. Specifically, you cannot run Promoted Listings reports in the Sandbox.

Promotions Manager

Promotions Manager lets sellers configure various types of discounts on the items in their inventory. The promotions can run for a specified period of time and they can include specific items, or items chosen via a specified item criteria. There are two types of discount promotions: markdown promotions, where sellers temporarily markdown the price of a selected set of times, and threshold promotions, where a promotion is triggered when a buyer meets a certain threshold.

For more information on discount promotions, see the Promotions Manager section of the Selling Integration Guide.

Promotions Manager technical overview

Promotions Manager has the following set of resources:

  • item_price_markdown – Create and manage direct price and percentage discounts using the methods in this resource.
  • item_promotion – Create and manage discounts that are triggered by a threshold using the methods in this resource. You can also use this resource to configure volume pricing promotions, where the buyer gets a higher discount when they purchase multiple items.
  • promotion – Retrieve a seller's promotions offered through Promotions Manager. You can also pause and resume promotions using this resource.
  • promotion_report – Retrieve a report that details the seller's promotions on a specified marketplace.
  • promotion_summary_report – Retrieve a report that summarizes the seller's promotions on a specified marketplace.

Promotions Manager use cases

The high-level use cases for the Promotions Manager are outlined below.

Create and manage markdown promotions

The Marketing API provides the basic Create, Read, Update, and Delete, or CRUD, operations for markdown promotions:

Create and manage threshold promotions

The methods in the item_promotion and promotion resources provide the basic CRUD operations for threshold promotions:

Create Promotions Manager reports

The item promotions service generates two types of reports for a seller's item promotions:

  • Item Promotions Report – Call getPromotionReports to retrieve a list of a seller's running, paused, and ended promotions. Use the report ID returned by this report to get the full summary report. You can filter the returned reports by marketplace and by the promotion state.
  • Summary Report – Call getPromotionSummaryReport to retrieve a report that summarizes a seller's promotions by marketplace.

For information on how to interpret the Summary Report, see Reading Promotions Manager Summary Reports.

Promotions Manager requirements and restrictions

Promotions Manager promotions are supported on the following eBay marketplaces:

  • Australia
  • France
  • Germany
  • Italy
  • Spain
  • United Kingdom
  • United States

Promotions Manager listing requirements

An item must meet the following listing requirements before it can be added to a Promotions Manager promotion:

  • The listing must be either a fixed price item or an Auction with a Buy It Now option. If you remove the Buy It Now option from an auction, the item is dropped from the promotion.
  • The listing must be an active listing on the same marketplace on which the promotion runs. For example, if you create a promotion for inventory that's actively listed on the US marketplace (EBAY_US), the promotion will not display on other marketplaces, even if you provide international shipping to other countries with an eBay marketplace. To clarify, suppose you run a promotion on an item listed on the US marketplace, but also ship to Australia. If you want to discount the item for domestic Australian buyers, you need to create a listing on the Australian site (, then run the promotion with that listing.
  • The listing must offer an electronic payment method.
Markdown promotion listing requirements

In addition, for markdown promotions, an item must be listed at the same price (the sum of the item price and shipping cost) without being part of a sale for a set number of days.

The following table lists the days that an item must be listed at stable price before it is eligible for an item price markdown promotion:

Marketplace Days Listed
Australia 10
France 30
Germany 30
Italy 30
Spain 30
United Kingdom 14

Note that for the US marketplace, you can add a listing to a markdown promotion as soon as you list the item.

Seller requirements

A seller must have an active eBay store subscription before they can use promoted listings with Promotions Manager.

Store Email Campaigns

Email marketing is one of the most powerful ways for reaching out to customers and building a community of repeat buyers. Using the email campaign methods, an eBay store seller can easily create and send email newsletter campaigns to subscribers, followers, and past customers who have signed up to receive newsletter from their store. A seller can use the email campaigns to welcome customers and to let customers know about new listings, promotions, sales, and discounts.

For more information on email campaigns, see the Store Email Campaigns section of the Selling Integration Guide.

Store email campaigns technical overview

Store Email Campaigns has the following resource:

  • email_campaign

The methods in this resource allow eBay store sellers to create, update, and delete email campaigns, as well as retrieve information about their campaigns.

Store email campaigns use cases

The high-level use cases for the Store Email Campaigns are outlined below.

Creating and managing store email campaigns

Sellers can use the createEmailCampaign method to create any of the six available email campaign types: New products & collections, Coupon, Sale event + markdown, Order discount, and Volume pricing. Sellers can then see a preview of their campaign using the getEmailPreview method.

For more information, see Creating, updating, and deleting email campaigns.

Retrieve reports on a store email campaign

The getEmailReport method retrieves performance data on all active email campaigns for a specified time period.

For more information, see Email Campaign reports.