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 and generate reports. The overview contains the following sections:

Technical overview

The following lists the main objects of the Marketing API.

  • CAMPAIGN
    • Ads (the promoted listings)

    • Campaign ID

    • Marketplace ID (site where campaign is hosted)

    • Campaign Name

    • Funding strategy (seller fee)

    • Start and end dates

      Listing ID (seller inventory reference or eBay listing IDs)

  • 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
  • AD_REPORT - Downloads a promoted listings report
  • AD_REPORT_METADATA - Retrieves the metadata for any report
  • AD_REPORT_TASK - Defines and generates various reports
    • Campaign IDs
    • Dimensions
    • Seller inventory references IDs
    • eBay listing IDs
    • Marketplace ID
    • Metrics
    • To and from date
    • Report format and type
  • ITEM_PROMOTION
    • Discount rules
    • Inventory criterion
    • Start and end dates
    • Marketplace ID (site where promotion is hosted)
    • Promotion name and description
    • Image URL
    • Promotion status
  • PROMOTION
    • Promotion ID
  • PROMOTION_REPORT
    • Marketplace ID (site where promotion is hosted)
    • Promotion status
  • PROMOTION_SUMMARY_REPORT
    • Marketplace ID (site where promotion is hosted)

Business use cases

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

Create an inventory based item promotions

You create an item promotion using the Create Item Promotioncall and include the discount rules of the promotion, the list of items and the basic information for the promotion, such as start and end dates, marketplace, etc.

Create a rule based promotions

You create an item promotion using the Create Item Promotioncall and include the discount rules of the promotion, a 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

You create an inventory based promoted listings campaign using 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 resource calls, such as Bulk Create Ads By Inventory Reference ID or Bulk Create Ads 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 summary and performance reports

The Marketing API lets you generates reports the sellers promotions and promoted listings.

Promotions manager reports

For the seller's promotions, you can generate a performance report at a promotion and a summary report for all the seller's Promotions manager promotions (Active, Scheduled, Draft, Paused, Ended) for the specified eBay marketplace.

Promoted listings reports

For the seller's promoted listings, you can generate account and campaign summary reports and performance reports for campaigns and listings. See Promoted Listings Reports Details for details.

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 ebay.com. The promotion will show up only on ebay.com, even if the items can be shipped to another country, such as Australia. To create a promotion for domestic Australian buyers on ebay.com.au, you would need to accept the Australian terms and conditions and create the promotion on ebay.com.au with your active listings on that site.

The following lists the seller and listing requirements for promotions.

Promoted listings requirements and restrictions

Promoted listings is supported on the US (United States), UK (United Kingdom), DE (Germany), and AU (Australia) sites.

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