Skip to main content

  • Important: Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made by EU/UK sellers. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signature to be included in the HTTP payload.

  • OpenAPI Specification - Version 2.0 for all of our RESTful APIs will no longer be available starting April 5, 2023. We will continue leveraging OpenAPI Specification - Version 3.0 for new features in our RESTful APIs.

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 NameHTTP MethodPathSummarySamples
bulkCreateAdsByInventoryReferencePOST/ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_referenceCreates 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
bulkCreateAdsByListingIdPOST/ad_campaign/{campaign_id}/bulk_create_ads_by_listing_idCreates 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
bulkDeleteAdsByInventoryReferencePOST/ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_referenceDeletes 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
bulkDeleteAdsByListingIdPOST/ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_idDeletes a set of ads from a campaign by listing ID values.View bulkDeleteAdsByListingId - /ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_id
bulkUpdateAdsBidByInventoryReferencePOST/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_referenceUpdates 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
bulkUpdateAdsBidByListingIdPOST/ad_campaign/{campaign_id}/bulk_update_ads_bid_by_listing_idUpdates 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
bulkUpdateAdsStatusPOST/ad_campaign/{campaign_id}/bulk_update_ads_statusUpdates the status of ads in bulk.View bulkUpdateAdsStatus - /ad_campaign/{campaign_id}/bulk_update_ads_status
bulkUpdateAdsStatusByListingIdPOST/ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_idUpdates the status of ads in bulk, based on listing ID values.View bulkUpdateAdsStatusByListingId - /ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_id
createAdByListingIdPOST/ad_campaign/{campaign_id}/adCreates an ad using a listing ID and associates it with a campaign.View createAdByListingId - /ad_campaign/{campaign_id}/ad
createAdsByInventoryReferencePOST/ad_campaign/{campaign_id}/create_ads_by_inventory_referenceCreates 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
deleteAdDELETE/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}
deleteAdsByInventoryReferencePOST/ad_campaign/{campaign_id}/delete_ads_by_inventory_referenceDeletes ads from a campaign by Inventory API inventory reference ID.View deleteAdsByInventoryReference - /ad_campaign/{campaign_id}/delete_ads_by_inventory_reference
getAdGET/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}
getAdsGET/ad_campaign/{campaign_id}/adRetrieves all the ads associated with a campaign ID, or the running ads by listing ID values.View getAds - /ad_campaign/{campaign_id}/ad
getAdsByInventoryReferenceGET/ad_campaign/{campaign_id}/get_ads_by_inventory_referenceRetrieves ads from a campaign by Inventory API inventory reference IDs.View getAdsByInventoryReference - /ad_campaign/{campaign_id}/get_ads_by_inventory_reference
updateBidPOST/ad_campaign/{campaign_id}/ad/{ad_id}/update_bidUpdates the bid for an ad ID by campaign ID.View updateBid - /ad_campaign/{campaign_id}/ad/{ad_id}/update_bid

ad_group

Method NameHTTP MethodPathSummarySamples
createAdGroupPOST/ad_campaign/{campaign_id}/ad_groupThis method creates ad groups. One or more ad groups can be created per campaign.View createAdGroup - /ad_campaign/{campaign_id}/ad_group
getAdGroupGET/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}
getAdGroupsGET/ad_campaign/{campaign_id}/ad_groupRetrieves ad groups based on a specified campaign ID.View getAdGroups - /ad_campaign/{campaign_id}/ad_group
suggestBidsPOST/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bidsSuggests bid rates for keywords.View suggestBids - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids
suggestKeywordsPOST/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywordsSuggests keywords to be used in Promoted Listings campaigns.View suggestKeywords - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords
updateAdGroupPUT/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 NameHTTP MethodPathSummarySamples
cloneCampaignPOST/ad_campaign/{campaign_id}/cloneClones a selection-rule based campaign.View cloneCampaign - /ad_campaign/{campaign_id}/clone
createCampaignPOST/ad_campaignCreates a Promoted Listings ad campaign.View createCampaign - /ad_campaign
deleteCampaignDELETE/ad_campaign/{campaign_id}Deletes a campaign that has ended by campaign ID.View deleteCampaign - /ad_campaign/{campaign_id}
endCampaignPOST/ad_campaign/{campaign_id}/endEnds a RUNNING or PAUSED campaign.
You can clone ended campaigns with cloneCampaign.
View endCampaign - /ad_campaign/{campaign_id}/end
findCampaignByAdReferenceGET/ad_campaign/find_campaign_by_ad_referenceRetrieves a campaign by listing ID, or by inventory reference ID and reference type pair.View findCampaignByAdReference - /ad_campaign/find_campaign_by_ad_reference
getCampaignGET/ad_campaign/{campaign_id}Retrieves the details of a campaign by campaign ID.View getCampaign - /ad_campaign/{campaign_id}
getCampaignByNameGET/ad_campaign/get_campaign_by_nameRetrieves the details of a campaign by campaign name.View getCampaignByName - /ad_campaign/get_campaign_by_name
getCampaignsGET/ad_campaignRetrieves the details of all of a seller's campaigns.
You can filter and paginate the result set.
View getCampaigns - /ad_campaign
pauseCampaignPOST/ad_campaign/{campaign_id}/pausePauses a RUNNING campaign.View pauseCampaign - /ad_campaign/{campaign_id}/pause
resumeCampaignPOST/ad_campaign/{campaign_id}/resumeResumes a PAUSED campaign.View resumeCampaign - /ad_campaign/{campaign_id}/resume
suggestItemsGET/ad_campaign/{campaign_id}/suggest_itemsProvides suggestions for a Promoted Listings campaign.View suggestItems - /ad_campaign/{campaign_id}/suggest_items
updateAdRateStrategyPOST/ad_campaign/{campaign_id}/update_ad_rate_strategyUpdates the ad rate strategy for a campaign based on the specified campaign ID.View updateAdRateStrategy - /ad_campaign/{campaign_id}/update_ad_rate_strategy
updateCampaignBudgetPOST/ad_campaign/{campaign_id}/update_campaign_budgetUpdates the budget for a campaign based on the specified campaign ID.View updateCampaignBudget - /ad_campaign/{campaign_id}/update_campaign_budget
updateCampaignIdentificationPOST/ad_campaign/{campaign_id}/update_campaign_identificationUpdates a campaign's name, start date, and end date by campaign ID.View updateCampaignIdentification - /ad_campaign/{campaign_id}/update_campaign_identification

keyword

Method NameHTTP MethodPathSummarySamples
bulkCreateKeywordPOST/ad_campaign/{campaign_id}/bulk_create_keywordCreates a set of keywords in bulk for a specified campaign.View bulkCreateKeyword - /ad_campaign/{campaign_id}/bulk_create_keyword
bulkUpdateKeywordPOST/ad_campaign/{campaign_id}/bulk_update_keywordUpdates keywords for a campaign in bulk.View bulkUpdateKeyword - /ad_campaign/{campaign_id}/bulk_update_keyword
createKeywordPOST/ad_campaign/{campaign_id}/keywordCreates a keyword for the specified Promoted Listings campaign.View createKeyword - /ad_campaign/{campaign_id}/keyword
getKeywordGET/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}
getKeywordsGET/ad_campaign/{campaign_id}/keywordRetrieves keywords based on the specified campaign ID.View getKeywords - /ad_campaign/{campaign_id}/keyword
updateKeywordPUT/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 NameHTTP MethodPathSummarySamples
bulkCreateNegativeKeywordPOST/bulk_create_negative_keywordCreates a set of negative keywords in bulk for a specified campaign and ad group.View bulkCreateNegativeKeyword - /bulk_create_negative_keyword
bulkUpdateNegativeKeywordPOST/bulk_update_negative_keywordUpdates the statuses for a set of negative keywords in bulk.View bulkUpdateNegativeKeyword - /bulk_update_negative_keyword
createNegativeKeywordPOST/negative_keywordCreates a negative keyword for a specified campaign and ad group.View createNegativeKeyword - /negative_keyword
getNegativeKeywordGET/negative_keyword/{negative_keyword_id}Retrieves the details for a negative keyword using the negative keyword ID.View getNegativeKeyword - /negative_keyword/{negative_keyword_id}
getNegativeKeywordsGET/negative_keywordRetrieves a set of negative keywords, filtered according to the specified query parameters.View getNegativeKeywords - /negative_keyword
updateNegativeKeywordPUT/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 NameHTTP MethodPathSummarySamples
getReportGET/ad_report/{report_id}Downloads a Promoted Listings report by ID.View getReport - /ad_report/{report_id}

ad_report_metadata

Method NameHTTP MethodPathSummarySamples
getReportMetadataGET/ad_report_metadataRetrieves metadata that details the fields returned in all Promoted Listings reports.View getReportMetadata - /ad_report_metadata
getReportMetadataForReportTypeGET/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 NameHTTP MethodPathSummarySamples
createReportTaskPOST/ad_report_taskCreates a report task, which generates a Promoted Listings report.View createReportTask - /ad_report_task
deleteReportTaskDELETE/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}
getReportTaskGET/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}
getReportTasksGET/ad_report_taskRetrieves 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 NameHTTP MethodPathSummarySamples
createItemPriceMarkdownPromotionPOST/item_price_markdownCreates a markdown promotion.View createItemPriceMarkdownPromotion - /item_price_markdown
deleteItemPriceMarkdownPromotionDELETE/item_price_markdown/{promotion_id}Deletes a markdown promotion by ID.View deleteItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}
getItemPriceMarkdownPromotionGET/item_price_markdown/{promotion_id}Gets a markdown promotion by ID.View getItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}
updateItemPriceMarkdownPromotionPUT/item_price_markdown/{promotion_id}Updates an existing markdown promotion by ID.View updateItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}

item_promotion

Method NameHTTP MethodPathSummarySamples
createItemPromotionPOST/item_promotionCreates an item promotion (also know as a threshold promotion).View createItemPromotion - /item_promotion
deleteItemPromotionDELETE/item_promotion/{promotion_id}Deletes a threshold promotion, except any that are actively running.View deleteItemPromotion - /item_promotion/{promotion_id}
getItemPromotionGET/item_promotion/{promotion_id}Retrieves the details of a threshold promotion by promotion ID.View getItemPromotion - /item_promotion/{promotion_id}
updateItemPromotionPUT/item_promotion/{promotion_id}Updates a the details of a threshold promotion by ID.View updateItemPromotion - /item_promotion/{promotion_id}

promotion

Method NameHTTP MethodPathSummarySamples
getListingSetGET/promotion/{promotion_id}/get_listing_setRetrieves the set of listings linked to a promotion ID.View getListingSet - /promotion/{promotion_id}/get_listing_set
getPromotionsGET/promotionRetrieves a seller's promotions by marketplace.View getPromotions - /promotion
pausePromotionPOST/promotion/{promotion_id}/pausePauses a RUNNING promotion.View pausePromotion - /promotion/{promotion_id}/pause
resumePromotionPOST/promotion/{promotion_id}/resumeRestarts a PAUSED promotion.View resumePromotion - /promotion/{promotion_id}/resume

promotion_report

Method NameHTTP MethodPathSummarySamples
getPromotionReportsGET/promotion_reportReturns a Promotions Manager Report by marketplace.View getPromotionReports - /promotion_report

promotion_summary_report

Method NameHTTP MethodPathSummarySamples
getPromotionSummaryReportGET/promotion_summary_reportReturns a Promotions Manager Summary Report by marketplace.View getPromotionSummaryReport - /promotion_summary_report