Marketing API resources

The Marketing API offers two platforms that sellers can use to promote and advertise their products:

• Promoted Listings is an eBay ad service that lets sellers set up ad campaigns for the products they want to promote. eBay displays the ads in search results and in other marketing modules as SPONSORED listings. If an item in a Promoted Listings campaign sells, the seller is assessed a Promoted Listings fee, which is a seller-specified percentage applied to the sales price. For complete details, refer to the Promoted Listings playbook.
• Promotions Manager gives sellers a way to offer discounts on specific items as a way to attract buyers to their inventory. Sellers can set up discounts (such as "20% off" and other types of offers) on specific items or on an entire customer order. To further attract buyers, eBay prominently displays promotion teasers throughout buyer flows. For complete details, see Promotions Manager.

Marketing reports, on both the Promoted Listings and Promotions Manager platforms, give sellers information that shows the effectiveness of their marketing strategies. The data gives sellers the ability to review and fine tune their marketing efforts.

Important! Sellers must have an active eBay Store subscription, and they must accept the Terms and Conditions before they can make requests to these APIs in the Production environment. There are also site-specific listings requirements and restrictions associated with these marketing tools, as listed in the "requirements and restrictions" sections for Promoted Listings and Promotions Manager.

The table below lists all the Marketing API calls grouped by resource.

ad

Method Name	HTTP Method	Path	Summary	Samples
bulkCreateAdsByInventoryReference	POST	/ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference	Creates ads for a list of Inventory API inventory reference IDs and associates the ads with a campaign.	View bulkCreateAdsByInventoryReference - /ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference
bulkCreateAdsByListingId	POST	/ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id	Creates ads based on a set of listing IDs and associates the ads with a campaign.	View bulkCreateAdsByListingId - /ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id
bulkDeleteAdsByInventoryReference	POST	/ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_reference	Deletes a set of ads from a campaign by an Inventory API inventory reference ID.	View bulkDeleteAdsByInventoryReference - /ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_reference
bulkDeleteAdsByListingId	POST	/ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_id	Deletes a set of ads from a campaign by listing ID values.	View bulkDeleteAdsByListingId - /ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_id
bulkUpdateAdsBidByInventoryReference	POST	/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_reference	Updates the bid percentage for items in a campaign by inventory reference ID.	View bulkUpdateAdsBidByInventoryReference - /ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_reference
bulkUpdateAdsBidByListingId	POST	/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_listing_id	Updates the bid percentage for items in a campaign by listing ID values.	View bulkUpdateAdsBidByListingId - /ad_campaign/{campaign_id}/bulk_update_ads_bid_by_listing_id
bulkUpdateAdsStatus	POST	/ad_campaign/{campaign_id}/bulk_update_ads_status	Updates the status of ads in bulk.	View bulkUpdateAdsStatus - /ad_campaign/{campaign_id}/bulk_update_ads_status
bulkUpdateAdsStatusByListingId	POST	/ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_id	Updates the status of ads in bulk, based on listing ID values.	View bulkUpdateAdsStatusByListingId - /ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_id
createAdByListingId	POST	/ad_campaign/{campaign_id}/ad	Creates an ad using a listing ID and associates it with a campaign.	View createAdByListingId - /ad_campaign/{campaign_id}/ad
createAdsByInventoryReference	POST	/ad_campaign/{campaign_id}/create_ads_by_inventory_reference	Creates an ad using an Inventory API inventory reference ID and associates it with a campaign.	View createAdsByInventoryReference - /ad_campaign/{campaign_id}/create_ads_by_inventory_reference
deleteAd	DELETE	/ad_campaign/{campaign_id}/ad/{ad_id}	Deletes an ad by ad ID and campaign ID.	View deleteAd - /ad_campaign/{campaign_id}/ad/{ad_id}
deleteAdsByInventoryReference	POST	/ad_campaign/{campaign_id}/delete_ads_by_inventory_reference	Deletes ads from a campaign by Inventory API inventory reference ID.	View deleteAdsByInventoryReference - /ad_campaign/{campaign_id}/delete_ads_by_inventory_reference
getAd	GET	/ad_campaign/{campaign_id}/ad/{ad_id}	Retrieves an ad by ad ID and campaign ID.	View getAd - /ad_campaign/{campaign_id}/ad/{ad_id}
getAds	GET	/ad_campaign/{campaign_id}/ad	Retrieves all the ads associated with a campaign ID, or the running ads by listing ID values.	View getAds - /ad_campaign/{campaign_id}/ad
getAdsByInventoryReference	GET	/ad_campaign/{campaign_id}/get_ads_by_inventory_reference	Retrieves ads from a campaign by Inventory API inventory reference IDs.	View getAdsByInventoryReference - /ad_campaign/{campaign_id}/get_ads_by_inventory_reference
updateBid	POST	/ad_campaign/{campaign_id}/ad/{ad_id}/update_bid	Updates the bid for an ad ID by campaign ID.	View updateBid - /ad_campaign/{campaign_id}/ad/{ad_id}/update_bid

ad_group

Method Name	HTTP Method	Path	Summary	Samples
createAdGroup	POST	/ad_campaign/{campaign_id}/ad_group	This method creates ad groups. One or more ad groups can be created per campaign.	View createAdGroup - /ad_campaign/{campaign_id}/ad_group
getAdGroup	GET	/ad_campaign/{campaign_id}/ad_group/{ad_group_id}	Retrieves ad group details based on adGroupId and campaignId.	View getAdGroup - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}
getAdGroups	GET	/ad_campaign/{campaign_id}/ad_group	Retrieves ad groups based on a specified campaign ID.	View getAdGroups - /ad_campaign/{campaign_id}/ad_group
suggestBids	POST	/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids	Suggests bid rates for keywords.	View suggestBids - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids
suggestKeywords	POST	/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords	Suggests keywords to be used in Promoted Listings campaigns.	View suggestKeywords - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords
updateAdGroup	PUT	/ad_campaign/{campaign_id}/ad_group/{ad_group_id}	Updates an ad group based on adGroupId and campaignId.	View updateAdGroup - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}

campaign

Method Name	HTTP Method	Path	Summary	Samples
cloneCampaign	POST	/ad_campaign/{campaign_id}/clone	Clones a selection-rule based campaign.	View cloneCampaign - /ad_campaign/{campaign_id}/clone
createCampaign	POST	/ad_campaign	Creates a Promoted Listings ad campaign.	View createCampaign - /ad_campaign
deleteCampaign	DELETE	/ad_campaign/{campaign_id}	Deletes a campaign that has ended by campaign ID.	View deleteCampaign - /ad_campaign/{campaign_id}
endCampaign	POST	/ad_campaign/{campaign_id}/end	Ends a RUNNING or PAUSED campaign. You can clone ended campaigns with cloneCampaign.	View endCampaign - /ad_campaign/{campaign_id}/end
findCampaignByAdReference	GET	/ad_campaign/find_campaign_by_ad_reference	Retrieves a campaign by listing ID, or by inventory reference ID and reference type pair.	View findCampaignByAdReference - /ad_campaign/find_campaign_by_ad_reference
getCampaign	GET	/ad_campaign/{campaign_id}	Retrieves the details of a campaign by campaign ID.	View getCampaign - /ad_campaign/{campaign_id}
getCampaignByName	GET	/ad_campaign/get_campaign_by_name	Retrieves the details of a campaign by campaign name.	View getCampaignByName - /ad_campaign/get_campaign_by_name
getCampaigns	GET	/ad_campaign	Retrieves the details of all of a seller's campaigns. You can filter and paginate the result set.	View getCampaigns - /ad_campaign
pauseCampaign	POST	/ad_campaign/{campaign_id}/pause	Pauses a RUNNING campaign.	View pauseCampaign - /ad_campaign/{campaign_id}/pause
resumeCampaign	POST	/ad_campaign/{campaign_id}/resume	Resumes a PAUSED campaign.	View resumeCampaign - /ad_campaign/{campaign_id}/resume
suggestItems	GET	/ad_campaign/{campaign_id}/suggest_items	Provides suggestions for a Promoted Listings campaign.	View suggestItems - /ad_campaign/{campaign_id}/suggest_items
updateAdRateStrategy	POST	/ad_campaign/{campaign_id}/update_ad_rate_strategy	Updates the ad rate strategy for a campaign based on the specified campaign ID.	View updateAdRateStrategy - /ad_campaign/{campaign_id}/update_ad_rate_strategy
updateCampaignBudget	POST	/ad_campaign/{campaign_id}/update_campaign_budget	Updates the budget for a campaign based on the specified campaign ID.	View updateCampaignBudget - /ad_campaign/{campaign_id}/update_campaign_budget
updateCampaignIdentification	POST	/ad_campaign/{campaign_id}/update_campaign_identification	Updates a campaign's name, start date, and end date by campaign ID.	View updateCampaignIdentification - /ad_campaign/{campaign_id}/update_campaign_identification

keyword

Method Name	HTTP Method	Path	Summary	Samples
bulkCreateKeyword	POST	/ad_campaign/{campaign_id}/bulk_create_keyword	Creates a set of keywords in bulk for a specified campaign.	View bulkCreateKeyword - /ad_campaign/{campaign_id}/bulk_create_keyword
bulkUpdateKeyword	POST	/ad_campaign/{campaign_id}/bulk_update_keyword	Updates keywords for a campaign in bulk.	View bulkUpdateKeyword - /ad_campaign/{campaign_id}/bulk_update_keyword
createKeyword	POST	/ad_campaign/{campaign_id}/keyword	Creates a keyword for the specified Promoted Listings campaign.	View createKeyword - /ad_campaign/{campaign_id}/keyword
getKeyword	GET	/ad_campaign/{campaign_id}/keyword/{keyword_id}	Retrieves a keyword based on the specified campaign ID and keyword ID.	View getKeyword - /ad_campaign/{campaign_id}/keyword/{keyword_id}
getKeywords	GET	/ad_campaign/{campaign_id}/keyword	Retrieves keywords based on the specified campaign ID.	View getKeywords - /ad_campaign/{campaign_id}/keyword
updateKeyword	PUT	/ad_campaign/{campaign_id}/keyword/{keyword_id}	Updates a keyword based on the specified campaign ID and the keyword ID.	View updateKeyword - /ad_campaign/{campaign_id}/keyword/{keyword_id}

negative_keyword

Method Name	HTTP Method	Path	Summary	Samples
bulkCreateNegativeKeyword	POST	/bulk_create_negative_keyword	Creates a set of negative keywords in bulk for a specified campaign and ad group.	View bulkCreateNegativeKeyword - /bulk_create_negative_keyword
bulkUpdateNegativeKeyword	POST	/bulk_update_negative_keyword	Updates the statuses for a set of negative keywords in bulk.	View bulkUpdateNegativeKeyword - /bulk_update_negative_keyword
createNegativeKeyword	POST	/negative_keyword	Creates a negative keyword for a specified campaign and ad group.	View createNegativeKeyword - /negative_keyword
getNegativeKeyword	GET	/negative_keyword/{negative_keyword_id}	Retrieves the details for a negative keyword using the negative keyword ID.	View getNegativeKeyword - /negative_keyword/{negative_keyword_id}
getNegativeKeywords	GET	/negative_keyword	Retrieves a set of negative keywords, filtered according to the specified query parameters.	View getNegativeKeywords - /negative_keyword
updateNegativeKeyword	PUT	/negative_keyword/{negative_keyword_id}	Updates the status of a negative keyword using its negative keyword ID.	View updateNegativeKeyword - /negative_keyword/{negative_keyword_id}

ad_report

Method Name	HTTP Method	Path	Summary	Samples
getReport	GET	/ad_report/{report_id}	Downloads a Promoted Listings report by ID.	View getReport - /ad_report/{report_id}

ad_report_metadata

Method Name	HTTP Method	Path	Summary	Samples
getReportMetadata	GET	/ad_report_metadata	Retrieves metadata that details the fields returned in all Promoted Listings reports.	View getReportMetadata - /ad_report_metadata
getReportMetadataForReportType	GET	/ad_report_metadata/{report_type}	Retrieves metadata that details the fields returned in a specific Promoted Listings report.	View getReportMetadataForReportType - /ad_report_metadata/{report_type}

ad_report_task

Method Name	HTTP Method	Path	Summary	Samples
createReportTask	POST	/ad_report_task	Creates a report task, which generates a Promoted Listings report.	View createReportTask - /ad_report_task
deleteReportTask	DELETE	/ad_report_task/{report_task_id}	Deletes a Promoted Listings report task, and any associated reports, by ID.	View deleteReportTask - /ad_report_task/{report_task_id}
getReportTask	GET	/ad_report_task/{report_task_id}	Retrieves the details on a Promoted Listings report task by ID.	View getReportTask - /ad_report_task/{report_task_id}
getReportTasks	GET	/ad_report_task	Retrieves a detailed list of the seller's report tasks. You can filter and paginate the result set.	View getReportTasks - /ad_report_task

item_price_markdown

Method Name	HTTP Method	Path	Summary	Samples
createItemPriceMarkdownPromotion	POST	/item_price_markdown	Creates a markdown promotion.	View createItemPriceMarkdownPromotion - /item_price_markdown
deleteItemPriceMarkdownPromotion	DELETE	/item_price_markdown/{promotion_id}	Deletes a markdown promotion by ID.	View deleteItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}
getItemPriceMarkdownPromotion	GET	/item_price_markdown/{promotion_id}	Gets a markdown promotion by ID.	View getItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}
updateItemPriceMarkdownPromotion	PUT	/item_price_markdown/{promotion_id}	Updates an existing markdown promotion by ID.	View updateItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}

item_promotion

Method Name	HTTP Method	Path	Summary	Samples
createItemPromotion	POST	/item_promotion	Creates an item promotion (also know as a threshold promotion).	View createItemPromotion - /item_promotion
deleteItemPromotion	DELETE	/item_promotion/{promotion_id}	Deletes a threshold promotion, except any that are actively running.	View deleteItemPromotion - /item_promotion/{promotion_id}
getItemPromotion	GET	/item_promotion/{promotion_id}	Retrieves the details of a threshold promotion by promotion ID.	View getItemPromotion - /item_promotion/{promotion_id}
updateItemPromotion	PUT	/item_promotion/{promotion_id}	Updates a the details of a threshold promotion by ID.	View updateItemPromotion - /item_promotion/{promotion_id}

promotion

Method Name	HTTP Method	Path	Summary	Samples
getListingSet	GET	/promotion/{promotion_id}/get_listing_set	Retrieves the set of listings linked to a promotion ID.	View getListingSet - /promotion/{promotion_id}/get_listing_set
getPromotions	GET	/promotion	Retrieves a seller's promotions by marketplace.	View getPromotions - /promotion
pausePromotion	POST	/promotion/{promotion_id}/pause	Pauses a RUNNING promotion.	View pausePromotion - /promotion/{promotion_id}/pause
resumePromotion	POST	/promotion/{promotion_id}/resume	Restarts a PAUSED promotion.	View resumePromotion - /promotion/{promotion_id}/resume

promotion_report

Method Name	HTTP Method	Path	Summary	Samples
getPromotionReports	GET	/promotion_report	Returns a Promotions Manager Report by marketplace.	View getPromotionReports - /promotion_report

promotion_summary_report

Method Name	HTTP Method	Path	Summary	Samples
getPromotionSummaryReport	GET	/promotion_summary_report	Returns a Promotions Manager Summary Report by marketplace.	View getPromotionSummaryReport - /promotion_summary_report