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.
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.
The high-level Promoted Listings use cases are outlined below.
The methods in the campaign resource provide the basic Create, Read, Update, and Delete, or CRUD, operations for Promoted Listings campaigns:
- Create a campaign with createCampaign. For complete details, see Creating a Promoted Listings campaign.
- 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.
- Update the bid percentage that's set for a specific item with updateBid.
- 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 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
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.
The high-level use cases for item promotions are outlined below.
The methods in the item_promotion and promotion resources provide the basic Create, Read, Update, and Delete, or CRUD, operations for item promotions:
- Create an item promotion with createItemPromotion.
- Get the details of an existing item promotion with getItemPromotion.
- Get the listings associated with a specific item promotion with getListingSet.
- Get a list of a seller's current promotions with getPromotions.
- Update the details of an item promotion with updateItemPromotion.
- Delete an item promotion with deleteItemPromotion.
Pause and restart item promotions
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.
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 (
- Australia (
- Germany (
- Great Britain (
Before a seller can create a Promoted Listings campaign, they must meet the following requirements:
- The seller must have an active eBay store subscription, or they must have a US or Global Top Rated Sellers status and be selling on the US marketplace.
- The seller 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:
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.
You can create item promotions only on the following eBay marketplaces:
- eBay US (
- Australia (
- Germany (
- Spain (
- France (
- Great Britain (
- Italy (
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 (
Before a seller can create item promotions, they must meet the following requirements:
- The seller must have an active eBay store subscription.
- The seller must accept the terms and conditions for the marketplace on which they want to create item promotions.
The table below lists the links to terms and conditions for the marketplaces that support item promotions:
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.