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.

Discounts manager is a free service that gives sellers the ability to offer price discounts on their items. For more information on Discounts manager, see the Discounts 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 strategies:

  • General strategy campaigns use the Cost Per Sale (CPS) funding model

  • Priority strategy campaigns use the Cost Per Click (CPC) funding model

  • Promote offsite 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 general and priority strategy 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 priority strategy 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 priority strategy 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 priority strategy campaigns. Negative keywords help prevent your priority strategy campaigns 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 general strategy campaign

General strategy campaigns offer sellers a simple and straightforward way to set up and manage their advertising campaign. General 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 general 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 promoting your listings with a general campaign strategy, see Promoted listings general strategy campaign creation flow.

Create a priority strategy campaign

Priority strategy campaigns offer sellers more control over their campaign through suggested bids, keywords, and ad groups. Priority 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 priority 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 priority campaigns: manual targeting and smart targeting. Details on each are shown below.

Create a manual targeting 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 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 priority strategy 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 campaigns, see Manual targeting campaigns.

Create a smart targeting 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 campaigns.

For more information, see Smart targeting campaigns .

Create a promote offsite campaign

A promote offsite campaign 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 promote offsite 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 campaigns, to retrieve the suggested budget for the campaign.

For more information on creating and managing an offsite campaign, see Promote offsite.

Note: Promote offsite campaigns are 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.

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 https://useragreement.ebay.com.au/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
Canada (English) CPS and CPC https://useragreement.ebay.ca/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
Canada (French) CPS and CPC https://useragreement.cafr.ebay.ca/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
France CPS and CPC https://useragreement.ebay.fr/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
Germany CPS and CPC https://useragreement.ebay.de/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
Italy CPS and CPC https://useragreement.ebay.it/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
Spain CPS and CPC https://useragreement.ebay.es/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
United Kingdom CPS and CPC https://useragreement.ebay.co.uk/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT
United States CPS and CPC https://useragreement.ebay.com/usragmt/agreement/PROMOTED_LISTINGS_USER_AGREEMENT

Promoted Listings listing requirements

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

  • For general strategy campaigns, the following listing formats are supported: 

    • Fixed price

    • Auction

    • Auction Buy It Now

  • For priority strategy campaigns, 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.

Discounts Manager

Discounts Manager let sellers configure various types of discounts on the items in their inventory. The discounts 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 discounts: markdown discounts, where sellers temporarily markdown the price of a selected set of times, and threshold discounts, where a discount is triggered when a buyer meets a certain threshold.

Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.

For more information on discounts, see the Discounts Manager section of the Selling Integration Guide.

Discounts Manager technical overview

Discounts 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 discounts, where the buyer gets a higher discount when they purchase multiple items.
  • promotion – Retrieve a seller's discounts offered through Discounts Manager. You can also pause and resume discounts using this resource.
  • promotion_report – Retrieve a report that details the seller's discounts on a specified marketplace.
  • promotion_summary_report – Retrieve a report that summarizes the seller's discounts on a specified marketplace.

Discounts Manager use cases

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

Create and manage markdown discounts

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

Create and manage threshold discounts

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

Create Discounts Manager reports

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

  • Item Promotions Report – Call getPromotionReports to retrieve a list of a seller's running, paused, and ended discounts. 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 discount state.
  • Summary Report – Call getPromotionSummaryReport to retrieve a report that summarizes a seller's discounts by marketplace.

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

Discounts Manager requirements and restrictions

Discounts Manager is supported on the following eBay marketplaces:

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

Discounts Manager listing requirements

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

  • 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 can no longer be discounted.
  • The listing must be an active listing on the same marketplace on which the discount runs. For example, if you create a discount for inventory that's actively listed on the US marketplace (EBAY_US), the discount 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 discount 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 (ebay.com.au), then run the discount with that listing.
  • The listing must offer an electronic payment method.
Markdown discount listing requirements

In addition, for markdown discounts, 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 discount:

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 discount as soon as you list the item.

Seller requirements

A seller must have an active eBay store subscription before they can use Discounts 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.