marketing APIv1.4.0

Marketing API overview

The Marketing API is a marketing and merchandising tool that can help sellers scale their sales by giving them the ability to offer appealing discounts and eye catching ad placements, all of which display in key spots throughout the eBay buying flows.

When online shoppers have more retail options than ever, giving visibility to your item listings with ad placements and discount offers can help to set your inventory apart from the masses. Whether it’s increasing basket size with a Buy 2, Get 20% Off deal, clearing out last season’s stock with simple offering $10 off the standard price, or showcasing key listings in prominent locations, the Marketing API lets sellers craft marketing schemes that match their business needs.

The Marketing API gives merchants and sellers the ability to create and manage both Promoted Listings ads and Promotions Manager discounts:

  • Promoted Listings is an eBay advertising service that highlights and promotes the listings that are included in a seller's ad campaigns.
  • Promotions Manager is a free service that lets sellers offer discounts on selected items as a way to increase visibility into their inventory.

The Marketing API also gives sellers the ability to run reports on their Promoted Listings ads and Promotions Manager discounts, which lets sellers 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 active eBay Store subscription and who has signed the Terms and Conditions for use of the service (see the Marketing API overview section below for details on the Terms and Conditions for each product). The Marketing API works with items that have been configured and placed into an eBay inventory with the Inventory API, and it works with listings created with the Trading API.

The rest of this topic is divided into two main sections:

Promoted Listings

This overview contains:

Promoted Listings technical overview

Promoted Listings is divided into the following set of resources, where each has 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 These are the fields that you use to 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.

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:

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.

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 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 (EBAY_US)
  • Australia (EBAY_AU)
  • Germany (EBAY_DE)
  • Great Britain (EBAY_GB)

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 a category supported by 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.

Seller requirements

Before a seller can create a Promoted Listings campaign, they must meet the following requirements:

Promotions Manager

This overview contains:

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. For example, you can configure the following with threshold promotions:
    • By 1 Get 1 Free
    • Spend $60, 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.

  • 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:

Create and manage threshold promotions

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

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

You can create markdown promotions on any eBay marketplace.

However, threshold promotions (using item_promotions) are supported only on the following eBay marketplaces:

  • eBay US (EBAY_US)
  • Australia (EBAY_AU)
  • Germany (EBAY_DE)
  • Spain (EBAY_ES)
  • France (EBAY_FR)
  • Great Britain (EBAY_GB)
  • Italy (EBAY_IT)

Promotions Manager creates promotions on a marketplace only for the items that are active on that marketplace. For example, after accepting the terms and conditions for the US eBay marketplace, you can create a promotion for any of your inventory that's actively listed on that marketplace ( The items that you promote on display only on that marketplace, even if your items can be shipped to another country, such as Australia. To create a promotion on the Australian marketplace ( for domestic Australian buyers, you need to accept the Australian terms and conditions, then create the promotions using the listings that are active on that site (

Promotions Manager listing requirements

An item must meet the following listing requirements before it can be added to a 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 a listing that is active on the same marketplace on which the promotion runs.
  • The listing must offer PayPal as a payment method.

Seller requirements

Before a seller can use Promotions Manager to create promotions, they must meet the following requirements: