The Marketing API is used to create and manage Promoted Listings campaigns and item promotions. Used separately or together, these two marketing features can increase views and sales of the seller's items.

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 items included in a seller's ad campaigns. There are two types of Promoted Listings campaigns:
  • 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
• Promotions Manager is a free service that give sellers the ability to offer price discounts on their items.

The following table outlines the key features of these two marketing methods.

Promoted Listings

Promotions Manager

Create advertisement campaigns to increase item visibility Promote items using IDs from either the Trading API or the Inventory API Add a set of listing IDs to an ad campaign Add items using rules Establish criteria for the items to be included in an ad campaign The rules can apply to existing listings for items, and they can apply to listings you create in the future. Leverage multiple funding models for campaigns Choose between the Cost Per Sale (CPS) funding model for Promoted Listings Standard campaigns, or the Cost Per Click (CPC) funding model for Promoted Listings Advanced campaigns, which creates more options for budget flexibility when promoting items. Leverage the Recommendation API to configure ad campaigns Sellers can use the Recommendations API to discover which of their active listings would likely benefit from Promoted Listings, and which ad rate, bid percentage, or budget would be most beneficial for boosting item sales. Adjust advertising strategies using report data Promoted Listings reports return targeted data that you can use to determine the performance of your ad campaigns. Fine-tune where to spend your advertising dollars by combining and analyzing data in the Promoted Listings reports with the data returned by the Analytics API.

Discounted listings can include IDs from either the Trading API or the Inventory API Item price markdown promotions Straight-forward monetary or percentage discounts on a seller's items Threshold promotions Discounts that trigger when a threshold is met Types of thresholds: Quantity trigger (i.e., Buy One Get One) Monetary value trigger Volume pricing (discount increases as quantity increases) Discounts can apply to either orders or items Use Promotions Manager reports to monitor your promotions The Summary Report details several key data points to help you monitor the effectiveness of your Promotions Manager discount promotions.

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.

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 items 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.

Promoted Listings

This overview contains:

• Promoted Listings technical overview
• Promoted Listings use cases
• Promoted Listings requirements and restrictions

Promoted Listings technical overview

Promoted Listings campaigns may operate with one of two funding models: Cost Per Sale (CPS) and Cost Per Click (CPC). Here are the resources supported for each model, where each has a set of methods that operate on that resource:

Resources supported by both the CPS and CPC funding models 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.

Resources supported by only the CPC funding model 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. The links lead to implementation information for each use case.

Create and manage Promoted Listings ad campaigns

The methods in the campaign resource provide the basic Create, Read, Update, and Delete, or CRUD, operations for Promoted Listings campaigns: Some operations differ depending on the funding model used for the campaign.

• Create a campaign with createCampaign. For complete details, see Promoted Listings campaign creation.
• 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.
• For campaigns that use the cost per sale funding model, update the bid percentage that's set for a specific item with updateBid.
• For campaigns that use the cost per click funding model, update the campaign budget that is set for a specific campaign with updateCampaignBudget.
• 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

Sellers can add items to Cost Per Sale (CPS) and Cost Per Click (CPC) campaigns using item keys. Note that items are added directly to campaigns for CPS-based funding models, whereas items are added to campaigns through the use of ad groups for CPC-based funding models.

Sellers can also add items to campaigns (CPS only) by specifying a set of rules that select the items to include in a campaign. For details, see Promoted Listings Standard campaign flow.

Add ad groups to campaigns

Sellers can add one or more ad groups to each Promoted Listings Advanced campaign that uses the Cost Per Click (CPC) funding model. To add an ad group to a campaign, use the default bid and specify the name of the ad group. For details, see Create an ad group for the PLA campaign.

Add keywords to ad groups

Sellers can add keywords to the ad group associated with a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model. For details, see Create keywords for the PLA campaign.

Add negative keywords to ad groups

Sellers can add negative keywords to ad groups in their associated Promoted Listings Advanced campaigns that use the Cost Per Click (CPC) funding model.

Negative keywords are used to specify the search criterion that should not trigger listings in an ad group, which helps prevent your Promoted Listings Advanced campaigns from surfacing unnecessarily when buyers run keyword searches that do not apply to your listings.

Pause and restart ad campaigns

You can pause a running campaign and later restart it using pauseCampaign and resumeCampaign. You can also end a campaign with with endCampaign.

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 and item promotions.

You can create Cost Per Sale (CPS) Promoted Listings Standard campaigns only on the following eBay marketplaces:

• Australia
• Canada (English)
• Canada (French)
• France
• Germany
• Italy
• Spain
• United Kingdom
• United States

You can create Cost Per Click (CPC) Promoted Listings Advanced campaigns only on the following eBay marketplaces:

• Australia
• Canada (English)
• Canada (French)
• France
• Germany
• Italy
• United Kingdom
• United States

Promoted Listings listing requirements

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

• The item must be a fixed price (Buy It Now) item.
• The item must be in one of the Promoted Listings supported categories.
• The item cannot be for real estate or motors.

Seller requirements

Before a seller can create a Promoted Listings campaign, they must be authorized by eBay.

In addition to the above requirement, 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, along with the supported funding models available 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	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

Promotions Manager

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:
  • Buy 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 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. 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 a 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

You can pause a running promotion and later restart it using pausePromotion and resumePromotion.

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 (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
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.