You are here: Sell APIs > Marketing API Overview

Marketing API Overview

The Marketing API lets sellers and merchants manage the life cycle of promoted listings and item promotions. The overview contains the following sections:

Technical overview

The following lists the main objects of the Marketing API.

    • Ads (the promoted listings)

    • Campaign Id

    • Marketplace Id (site where campaign is hosted)

    • Campaign Name

    • Funding strategy (seller fee)

    • Start and end dates

  • AD - Ads are generated in one of 3 ways:
    • From a set of rules that select the listings from the seller's inventory (brands, categoryIds, conditionIds, maxPrice, and minPrice)
    • A list of seller inventory listing Ids
    • A list of eBay listing Ids
    • An Id of a specific item

    • An Id of the parent of an item with variations, such as a shirt that is available in multiple sizes and colors

    • Discount rules
    • Inventory criterion
    • Start and end dates
    • Marketplace Id (site where promotion is hosted)
    • Promotion name and description
    • Image URL
    • Promotion status
    • Promotion Id

Business use cases

This section outlines the high-level use cases supported by the Marketing API.

Create an item promotion

You can create an item promotion using the Create Item Promotion call and include the discount rules of the promotion, the list of items or set of rules that are used to select the items, and the basic information for the promotion, such as start and end dates, marketplace, etc.

Create a rule based promoted listings campaign

You create a rule based campaign using the Create Campaign call and include one or more campaignCriterion containers, which define a set of rules that select the listings.

You can also recreate an existing rule base campaign using the Clone Campaign call. A campaign can be cloned only if it the campaign has ended.

Create an inventory based promoted listings campaign

To create an inventory based promoted listings campaign you use the Create Campaign call to create the campaign. Then you pass in a list of seller inventory Ids or eBay listing Ids using one of the AD calls, such as Create Ads in Bulk By Inventory Reference Id or Create Ads in Bulk By Listing Id.

Manage the life cycle of a promotions and campaigns

The Marketing API has the following capabilities that help you manage the complete life cycle of promotions and promoted listings campaigns.

  • Create, end, pause, resume, or delete a campaign
  • Create, pause, resume, delete a promotion
  • Update any fields of a campaign or promotion
  • Retrieve a specific campaign by name, campaign Id, or listing Id
  • Retrieve a promotion by Id
  • Retrieve the listings in a promotion
  • Retrieve ads by listing Ids
  • Retrieve all campaigns or promotions

Generate a promotion summary report

The Marketing API lets you generates a summary report for all the seller's Promotions manager promotions (Active, Scheduled, Draft, Paused, Ended) for the specified eBay marketplace.

API requirements and restrictions

The following section contains the requirement and restrictions for creating promotions and promoted listing campaigns.

Promotions manager requirements and restrictions

Promotions are supported on eBay US (United States), UK (United Kingdom), DE (Germany), AU (Australia), FR (France), IT (Italy), and ES (Spain).

You can create promotions on a site only for active items on that site. For example, after you have accepted the US terms and conditions, you can create a promotion for any of your inventory that you actively listed on The promotion will show up only on, even if the items can be shipped to another country, such as Australia. To create a promotion for domestic Australian buyers on, you would need to accept the Australian terms and conditions and create the promotion on with your active listings on that site.

The following lists the seller and listing requirements for promotions.

Promoted listings requirements and restrictions

Promoted Listings are supported on eBay US (United States), US-Motors (non-fitment listings), UK (United Kingdom), DE (Germany), AU (Australia). The following lists the seller and listing requirements for promoted listings.

Note: The Sandbox does not have all the functionality needed by the Promoted Listings service to do end-to-end testing.