The Marketing API is a marketing tool that sellers can use to scale sales by giving them the ability to offer appealing discounts and eye catching ad placements that display in key spots throughout the eBay buying flows.
The Marketing API is divided into two merchandising tools, Promoted Listings and Promotions Manager:
- Promoted Listings is an eBay advertising service that increases the visibility of listings included in a seller's ad campaigns.
- Promotions Manager is a free service that give sellers the ability to offer price discounts on their listings.
Here are the key features of these two marketing methods:
Promoting item listings
Shoppers have more retail options than ever and promoting your item listings with ad placements and discount offers can help to set your inventory apart from the masses.
Whether it’s showcasing key listings in prominent locations or increasing basket size with a Buy 2, Get 20% Off deal and clearing out last season’s stock with simple offering $10 off the standard price, the Marketing API lets sellers craft marketing schemes that match their business needs.
Sellers can run reports on Promoted Listings campaigns and Promotions Manager discounts to evaluate their marketing efforts and find the most effective ways to increase sales.
Note: The Marketing API is available to any seller who has an eBay Store subscription.
However, there are listing requirements and site restrictions for these marketing tools. For complete information on the Marketing API requirements, including product Terms and Conditions, see the Promoted Listings requirements and restrictions and Promotions Manager requirements and restrictions sections below.
The rest of this topic is divided into two main sections:
This overview contains:
- Promoted Listings technical overview
- Promoted Listings use cases
- Promoted Listings requirements and restrictions
Promoted Listings technical overview
Promoted Listings is divided into the following set of resources, where each has a set of methods that operate on that resource:
- campaign - Create and manage campaigns with the methods in this resource.
- ad - Add items, either individually or in bulk, to existing campaigns. You can also get a list of existing campaign ads, update bid percentages, and delete ads using this resource.
- ad_report_task - Create report tasks that initiate the generation of a Promoted Listings report. There is also a method to delete report tasks.
- ad_report - Retrieve a completed Promoted Listings report with the getReport.
- 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.
Promoted Listings use cases
The following use cases outline the high-level ways that sellers can take advantage of Promoted Listings. The links lead to implementation information for each use case.
The methods in the campaign resource provide the basic Create, Read, Update, and Delete, or CRUD, operations for Promoted Listings campaigns:
- Create a campaign with createCampaign. For complete details, see Creating a Promoted Listings campaign.
- Get the details of existing campaigns with the following methods: getCampaign, getCampaigns, and getCampaignByName.
- Find the campaign that includes a specific item with findCampaignByAdReference.
- Update a campaign's name, and it's start and end dates with updateCampaignIdentification.
- Update the bid percentage that's set for a specific item with updateBid.
- Clone a campaign that has ended, making it easy to continue a promotion that you've already created, with cloneCampaign.
- Delete campaigns with deleteCampaign.
Add items one at a time or in bulk to ad campaigns
Seller's can add inventory items to campaigns using item keys, or by specifying a set of rules that select the items to include in a campaign. For details, see Specifying the items to include in a campaign.
Tip: For recommendations on which listings are prime for a Promoted Listings ad campaign, and to get guidance on how to set the bidPercentage field, see Using the Recommendation API to help configure campaigns.
Pause and restart ad campaigns
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 Creating Promoted Listing reports.
Promoted Listings requirements and restrictions
This section details the requirement and restrictions pertaining to Promoted Listings campaigns and item promotions.
You can create Promoted Listings campaigns only on the following eBay marketplaces:
- eBay US (
- Australia (
- Germany (
- Great Britain (
Promoted Listings listing requirements
Before an item can be added to a Promoted Listings campaign, it must meet the following listing requirements:
- The listing must be a fixed price (Buy It Now) item.
- The listing must be a multiple-quantity listing.
- The listing must be in one of the categories that support Promoted Listings.
- The listing cannot be for real estate or motors.
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.
Before a seller can create a Promoted Listings campaign, they must meet the following requirements:
- In the US and Australia:
- The seller needs to be in good standing with an established sales history.
- In Great Britain and Germany:
- The seller must either register as a business or have a Shop, be in good standing, and have an established sales history.
In addition to the above requirements, all sellers must accept the terms and conditions for the marketplace on which they want to create Promoted Listings campaigns.
The table below lists the links to terms and conditions for the marketplaces that support Promoted Listings:
|Marketplace||Promoted Listings Terms and Conditions URLs|
This overview contains:
- Promotions Manager technical overview
- Promotions Manager use cases
- Promotions Manager requirements and restrictions
Promotions Manager technical overview
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.
Promotions Manager has two distinct types of discount promotions:
- Item price markdowns – Known simply as markdown promotions, these are simple promotions where sellers temporarily "markdown" the price of a selected set of items. The discounts can be either a monetary amount or a percentage off the normal price.
- Item promotions – Casually called threshold promotions, sellers configure these promotions to trigger when the buyer meets a certain "threshold." Sellers can offer price and percentage discounts on either a set of items, or on an order. Promotions can also be configured where the more items a buyer purchases, the more they save. For example, you can configure the following with threshold promotions:
- By 1 Get 1 Free
- Spend $60, Get 20% off!
- Buy 2, get 10% off. Buy 3, get 20% off!
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 the 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 Discount Manager are outlined below. The links lead to implementation information for each use case.
Create and manage markdown promotions
The Marketing API provides the basic Create, Read, Update, and Delete, or CRUD, operations for markdown promotions:
- markdown an item promotion with createItemPriceMarkdownPromotion.
- Get the details of an existing markdown promotion with getItemPriceMarkdownPromotion.
- Update the details of an item promotion with updateItemPriceMarkdownPromotion.
- Delete an item promotion with deleteItemPriceMarkdownPromotion.
- Get the listings associated with a specific markdown promotion with getListingSet.
Create and manage threshold promotions
The methods in the item_promotion and promotion resources provide the basic CRUD operations for threshold promotions:
- Create an item promotion with createItemPromotion.
- Get the details of an existing item promotion with getItemPromotion.
- Update the details of an item promotion with updateItemPromotion.
- Delete an item promotion with deleteItemPromotion.
- Get a list of a seller's current promotions with getPromotions.
- Get the listings associated with a specific item promotion with getListingSet.
Create sales events by linking buyers to your discounted listings
When you promote an item with Promotions Manager, eBay creates web page with a static URL link to your promoted item. Create sales events and publish the links to your promotions in mailers and other marketing collateral, knowing the links will remain active.
Pause and restart Promotions Manager 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:
- eBay US (
- Australia (
- Germany (
- Spain (
- France (
- Great Britain (
- Italy (
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 (
ebay.com.au), 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 at a stable price|
Great Britan (
Note that for the US marketplace (
EBAY_US), you can add a listing to a markdown promotion as soon as you list the item.
A seller must have an active eBay store subscription before they can promoted listings with Promotions Manager.