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 |  (Limited Release) 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 | (Limited Release) 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 | (Limited Release) 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} | (Limited Release) 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 | (Limited Release) 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 | (Limited Release) 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 | (Limited Release) 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} | (Limited Release) 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 | (Limited Release) 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 | (Limited Release) 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 | (Limited Release) 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 | (Limited Release) Updates keywords for a campaign in bulk. | View bulkUpdateKeyword - /ad_campaign/{campaign_id}/bulk_update_keyword |
| createKeyword | POST | /ad_campaign/{campaign_id}/keyword | (Limited Release) 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} | (Limited Release) 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 | (Limited Release) Retrieves keywords based on the specified campaign ID. | View getKeywords - /ad_campaign/{campaign_id}/keyword |
| updateKeyword | PUT | /ad_campaign/{campaign_id}/keyword/{keyword_id} | (Limited Release) 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 | (Limited Release) 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 | (Limited Release) Updates the statuses for a set of negative keywords in bulk. | View bulkUpdateNegativeKeyword - /bulk_update_negative_keyword |
| createNegativeKeyword | POST | /negative_keyword | (Limited Release) Creates a negative keyword for a specified campaign and ad group. | View createNegativeKeyword - /negative_keyword |
| getNegativeKeyword | GET | /negative_keyword/{negative_keyword_id} | (Limited Release) Retrieves the details for a negative keyword using the negative keyword ID. | View getNegativeKeyword - /negative_keyword/{negative_keyword_id} |
| getNegativeKeywords | GET | /negative_keyword | (Limited Release) Retrieves a set of negative keywords, filtered according to the specified query parameters. | View getNegativeKeywords - /negative_keyword |
| updateNegativeKeyword | PUT | /negative_keyword/{negative_keyword_id} | (Limited Release) 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 |