marketing APIv1.3.0

Marketing API overview

The Marketing API is a marketing and merchandising tool that can help sellers scale their sales with appealing item discounts and eye catching ad placements that display in key spots in 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 by offering an extra 30% off, 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 and item promotions:

  • Promoted Listings is an eBay advertising service that highlights the listings that are part ad campaigns.
  • Item promotions provide a way for sellers to 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 and item promotions, 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. 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.

Technical overview

The Marketing API provides two key services, and each has a set of resources and methods that let you create, manage, and view the results of your marketing efforts.

The Promoted Listings resources

Promoted Listings has the following set of resources:

  • 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 the methods in this resource.
  • ad_report_task - Create report tasks that initiate the generation of a Promoted Listings report. You can also delete report tasks using the methods in this resource.
  • ad_report - Retrieve a completed Promoted Listings report with the getReport.
  • ad_report_metadata - Get the fields that are required and optional for the different types of
  • Promoted Listings reports. These are the fields that you use to create a report task.

The item promotions resources

Item promotions has the following set of resources:

  • item_promotion - Create and manage item promotions using the methods in this resource.

  • promotion - Retrieve a seller's current item promotions. You can also pause and resume item promotions using the methods in this resource.

  • promotion_report - Retrieve a report that details the seller's item promotions on a specified marketplace.

  • promotion_summary_report - Retrieve a report that summarizes the seller's item promotions on a specified marketplace.

Promoted Listings use cases

The high-level Promoted Listings use cases are outlined below.

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 to 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 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 Promoted Listings reports

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.

Item promotion use cases

The high-level use cases for item promotions are outlined below.

Create and manage item promotions

The methods in the item_promotion and promotion resources provide the basic Create, Read, Update, and Delete, or CRUD, operations for item promotions:

Pause and restart item promotions

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

Create item promotions reports

The item promotions service generates two types of reports for a seller's item promotions:

  • The 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.
  • The item promotions 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 item promotion Summary Reports.

Marketing API requirements and restrictions

This section details the requirement and restrictions pertaining to Promoted Listings campaigns and item promotions.

Promoted Listings requirements and restrictions

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)

Seller requirements

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

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

Item promotions requirements and restrictions

You can create item promotions 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)

You can create item promotions on a site only for the items that are active on that site. 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 (ebay.com). The items that you promote on ebay.com display only on that marketplace, 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 need to accept the Australian terms and conditions, then create item promotions using the listings that are active on that site (ebay.com.au).

Seller requirements

Before a seller can create item promotions, they must meet the following requirements:

Item listing requirements

Before an item can be added to an item promotion, it must meet the following listing requirements:

  • The listing must be a fixed price item, or an Auction with a Buy It Now option. If the Buy It Now option goes away, the item is not longer included in the item promotion.
  • The listing must be a listing that is active on the same marketplace on which the item promotion runs.
  • The listing must offer PayPal as a payment method.