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.

Store Email Campaign allows sellers to create and send email campaigns to customers who have signed up to receive their newsletter. For more information on email campaigns, see Store Email Campaigns.

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 in bulk, based on SKUs or inventory item groups.View bulkCreateAdsByInventoryReference - /ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference
bulkCreateAdsByListingIdPOST/ad_campaign/{campaign_id}/bulk_create_ads_by_listing_idCreates ads in bulk, based on listing ID values.View bulkCreateAdsByListingId - /ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id
bulkDeleteAdsByInventoryReferencePOST/ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_referenceDeletes ads in bulk, based on SKUs or inventory item groups.View bulkDeleteAdsByInventoryReference - /ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_reference
bulkDeleteAdsByListingIdPOST/ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_idDeletes ads in bulk, based on 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 ads in bulk, based on SKUs or inventory item groups.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 CPS ads in bulk, based on 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 CPC 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 CPC 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 based on a listing ID value 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 based on a SKU or an inventory item group 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 based on an 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 based on a SKU or an inventory item group.View deleteAdsByInventoryReference - /ad_campaign/{campaign_id}/delete_ads_by_inventory_reference
getAdGET/ad_campaign/{campaign_id}/ad/{ad_id}Retrieves an ad.View getAd - /ad_campaign/{campaign_id}/ad/{ad_id}
getAdsGET/ad_campaign/{campaign_id}/adRetrieves all ads for a campaign, or specific ads in the campaign according to search criteria.View getAds - /ad_campaign/{campaign_id}/ad
getAdsByInventoryReferenceGET/ad_campaign/{campaign_id}/get_ads_by_inventory_referenceRetrieves ads for a campaign, based on listing IDS, SKUs or inventory item groups.View getAdsByInventoryReference - /ad_campaign/{campaign_id}/get_ads_by_inventory_reference
updateBidPOST/ad_campaign/{campaign_id}/ad/{ad_id}/update_bidUpdates the bid percentage for a CPS ad.View updateBid - /ad_campaign/{campaign_id}/ad/{ad_id}/update_bid

ad_group

Method NameHTTP MethodPathSummarySamples
createAdGroupPOST/ad_campaign/{campaign_id}/ad_groupCreates an ad group.View createAdGroup - /ad_campaign/{campaign_id}/ad_group
getAdGroupGET/ad_campaign/{campaign_id}/ad_group/{ad_group_id}Retrieves an ad group.View getAdGroup - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}
getAdGroupsGET/ad_campaign/{campaign_id}/ad_groupRetrieves ad groups.View getAdGroups - /ad_campaign/{campaign_id}/ad_group
suggestBidsPOST/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bidsRetrieves suggested bid values for a set of keywords in an ad group.View suggestBids - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids
suggestKeywordsPOST/ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywordsRetrieves suggested keywords for an ad group.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.View updateAdGroup - /ad_campaign/{campaign_id}/ad_group/{ad_group_id}

campaign

Method NameHTTP MethodPathSummarySamples
cloneCampaignPOST/ad_campaign/{campaign_id}/cloneCopies an ended PLS campaign.View cloneCampaign - /ad_campaign/{campaign_id}/clone
createCampaignPOST/ad_campaignCreates an ad campaign.View createCampaign - /ad_campaign
deleteCampaignDELETE/ad_campaign/{campaign_id}Deletes an ended ad campaign.View deleteCampaign - /ad_campaign/{campaign_id}
endCampaignPOST/ad_campaign/{campaign_id}/endEnds an active or paused ad campaign.View endCampaign - /ad_campaign/{campaign_id}/end
findCampaignByAdReferenceGET/ad_campaign/find_campaign_by_ad_referenceRetrieves PLS ad campaign by listing ID, SKU, or inventory item group.View findCampaignByAdReference - /ad_campaign/find_campaign_by_ad_reference
getCampaignGET/ad_campaign/{campaign_id}Retrieves an ad campaign by campaign ID.View getCampaign - /ad_campaign/{campaign_id}
getCampaignByNameGET/ad_campaign/get_campaign_by_nameRetrieves an ad campaign by campaign name.View getCampaignByName - /ad_campaign/get_campaign_by_name
getCampaignsGET/ad_campaignRetrieves one or more ad campaigns based on search criteria.View getCampaigns - /ad_campaign
launchCampaignPOST/ad_campaign/{campaign_id}/launchLaunches a Quick Setup campaign in draft status.View launchCampaign - /ad_campaign/{campaign_id}/launch
pauseCampaignPOST/ad_campaign/{campaign_id}/pausePauses an active ad campaign.View pauseCampaign - /ad_campaign/{campaign_id}/pause
resumeCampaignPOST/ad_campaign/{campaign_id}/resumeResumes a paused ad campaign.View resumeCampaign - /ad_campaign/{campaign_id}/resume
setupQuickCampaignPOST/ad_campaign/setup_quick_campaignCreates a draft of a PLA campaign with one step.View setupQuickCampaign - /ad_campaign/setup_quick_campaign
suggestBudgetGET/ad_campaign/suggest_budgetRetrieves the suggested daily budget for an Offsite Ads campaign.View suggestBudget - /ad_campaign/suggest_budget
suggestItemsGET/ad_campaign/{campaign_id}/suggest_itemsRetrieves listings that are possible candidates to be added to a PLA campaign.View suggestItems - /ad_campaign/{campaign_id}/suggest_items
updateAdRateStrategyPOST/ad_campaign/{campaign_id}/update_ad_rate_strategyUpdates the ad rate strategy for a PLS campaign.View updateAdRateStrategy - /ad_campaign/{campaign_id}/update_ad_rate_strategy
updateBiddingStrategyPOST/ad_campaign/{campaign_id}/update_bidding_strategyThis method allows sellers to change their bidding strategy for a specified Cost Per Click (CPC) campaign.View updateBiddingStrategy - /ad_campaign/{campaign_id}/update_bidding_strategy
updateCampaignBudgetPOST/ad_campaign/{campaign_id}/update_campaign_budgetUpdates the daily budget for a PLA campaign.View updateCampaignBudget - /ad_campaign/{campaign_id}/update_campaign_budget
updateCampaignIdentificationPOST/ad_campaign/{campaign_id}/update_campaign_identificationUpdates an ad campaign's name, start date, and/or end date.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 for one or more ad groups in an existing PLA campaign.View bulkCreateKeyword - /ad_campaign/{campaign_id}/bulk_create_keyword
bulkUpdateKeywordPOST/ad_campaign/{campaign_id}/bulk_update_keywordUpdates the status and/or bid rates for one or more keywords in a PLA campaign.View bulkUpdateKeyword - /ad_campaign/{campaign_id}/bulk_update_keyword
createKeywordPOST/ad_campaign/{campaign_id}/keywordCreates a keyword for an ad group in a PLA campaign.View createKeyword - /ad_campaign/{campaign_id}/keyword
getKeywordGET/ad_campaign/{campaign_id}/keyword/{keyword_id}Retrieves details on a PLA campaign's keyword.View getKeyword - /ad_campaign/{campaign_id}/keyword/{keyword_id}
getKeywordsGET/ad_campaign/{campaign_id}/keywordRetrieves one or more keywords in a PLA campaign based on search criteria.View getKeywords - /ad_campaign/{campaign_id}/keyword
updateKeywordPUT/ad_campaign/{campaign_id}/keyword/{keyword_id}Updates the status and/or bid rate for a keyword in a PLA campaign.View updateKeyword - /ad_campaign/{campaign_id}/keyword/{keyword_id}

negative_keyword

Method NameHTTP MethodPathSummarySamples
bulkCreateNegativeKeywordPOST/bulk_create_negative_keywordCreates a set of negative keywords for one for more ad groups in an existing PLA campaign.View bulkCreateNegativeKeyword - /bulk_create_negative_keyword
bulkUpdateNegativeKeywordPOST/bulk_update_negative_keywordUpdates the status and/or bid rates for one or more keywords in a PLA campaign.View bulkUpdateNegativeKeyword - /bulk_update_negative_keyword
createNegativeKeywordPOST/negative_keywordCreates a negative keyword for an ad group in a PLA campaign.View createNegativeKeyword - /negative_keyword
getNegativeKeywordGET/negative_keyword/{negative_keyword_id}Retrieves details on a PLA campaign's negative keyword.View getNegativeKeyword - /negative_keyword/{negative_keyword_id}
getNegativeKeywordsGET/negative_keywordRetrieves one or more keywords in a PLA campaign based on search criteria.View getNegativeKeywords - /negative_keyword
updateNegativeKeywordPUT/negative_keyword/{negative_keyword_id}Updates the status and/or bid rate for a keyword in a PLA campaign.View updateNegativeKeyword - /negative_keyword/{negative_keyword_id}

ad_report

Method NameHTTP MethodPathSummarySamples
getReportGET/ad_report/{report_id}Downloads a Promoted Listings report.View getReport - /ad_report/{report_id}

ad_report_metadata

Method NameHTTP MethodPathSummarySamples
getReportMetadataGET/ad_report_metadataRetrieves metadata for each Promoted Listings report type.View getReportMetadata - /ad_report_metadata
getReportMetadataForReportTypeGET/ad_report_metadata/{report_type}Retrieves metadata for a specific Promoted Listings report type.View getReportMetadataForReportType - /ad_report_metadata/{report_type}

ad_report_task

Method NameHTTP MethodPathSummarySamples
createReportTaskPOST/ad_report_taskConfigures the settings and metrics of a Promoted Listings report that will be downloaded with the getReport method.View createReportTask - /ad_report_task
deleteReportTaskDELETE/ad_report_task/{report_task_id}Deletes a Promoted Listings report task.View deleteReportTask - /ad_report_task/{report_task_id}
getReportTaskGET/ad_report_task/{report_task_id}Retrieves the details on a Promoted Listings report task.View getReportTask - /ad_report_task/{report_task_id}
getReportTasksGET/ad_report_taskRetrieves details on all current Promoted Listings reports, with an option to filter by report status.View getReportTasks - /ad_report_task

item_price_markdown

Method NameHTTP MethodPathSummarySamples
createItemPriceMarkdownPromotionPOST/item_price_markdownCreates a markdown promotion and applies it to one or more active listings.View createItemPriceMarkdownPromotion - /item_price_markdown
deleteItemPriceMarkdownPromotionDELETE/item_price_markdown/{promotion_id}Deletes an inactive markdown promotion.View deleteItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}
getItemPriceMarkdownPromotionGET/item_price_markdown/{promotion_id}Retrieves details on a markdown promotion.View getItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}
updateItemPriceMarkdownPromotionPUT/item_price_markdown/{promotion_id}Updates an existing markdown promotion.View updateItemPriceMarkdownPromotion - /item_price_markdown/{promotion_id}

item_promotion

Method NameHTTP MethodPathSummarySamples
createItemPromotionPOST/item_promotionCreates an item promotion and applies it to one or more active listings.View createItemPromotion - /item_promotion
deleteItemPromotionDELETE/item_promotion/{promotion_id}Deletes an inactive item promotion.View deleteItemPromotion - /item_promotion/{promotion_id}
getItemPromotionGET/item_promotion/{promotion_id}Retrieves the details on an item promotion.View getItemPromotion - /item_promotion/{promotion_id}
updateItemPromotionPUT/item_promotion/{promotion_id}Updates an existing item promotion.View updateItemPromotion - /item_promotion/{promotion_id}

promotion

Method NameHTTP MethodPathSummarySamples
getListingSetGET/promotion/{promotion_id}/get_listing_setRetrieves a set of listings linked to an item promotion.View getListingSet - /promotion/{promotion_id}/get_listing_set
getPromotionsGET/promotionRetrieves one or more of a seller's item promotions for an eBay marketplace that match search criteria.View getPromotions - /promotion
pausePromotionPOST/promotion/{promotion_id}/pausePauses a RUNNING item promotion.View pausePromotion - /promotion/{promotion_id}/pause
resumePromotionPOST/promotion/{promotion_id}/resumeRestarts a PAUSED item promotion.View resumePromotion - /promotion/{promotion_id}/resume

promotion_report

Method NameHTTP MethodPathSummarySamples
getPromotionReportsGET/promotion_reportRetrieves detailed metrics for one or more of a seller's item promotions for an eBay marketplace that match search criteria.View getPromotionReports - /promotion_report

promotion_summary_report

Method NameHTTP MethodPathSummarySamples
getPromotionSummaryReportGET/promotion_summary_reportRetrieves summarized sales data for all of a seller's non-ended item promotions for a specified marketplace.View getPromotionSummaryReport - /promotion_summary_report

email_campaign

Method NameHTTP MethodPathSummarySamples
createEmailCampaignPOST/email_campaignCreates a Store email campaign.View createEmailCampaign - /email_campaign
deleteEmailCampaignDELETE/email_campaign/{email_campaign_id}Deletes a Store email campaign.View deleteEmailCampaign - /email_campaign/{email_campaign_id}
getAudiencesGET/email_campaign/audienceRetrieves all of a seller's audience groups for a specified Store email campaign type.View getAudiences - /email_campaign/audience
getEmailCampaignGET/email_campaign/{email_campaign_id}Retrieves a Store email campaign.View getEmailCampaign - /email_campaign/{email_campaign_id}
getEmailCampaignsGET/email_campaignRetrieves a list of Store email campaigns that match search criteria.View getEmailCampaigns - /email_campaign
getEmailPreviewGET/email_campaign/{email_campaign_id}/email_previewRetrieves the raw HTML content of the email body associated with a Store email campaign.View getEmailPreview - /email_campaign/{email_campaign_id}/email_preview
getEmailReportGET/email_campaign/reportRetrieves a seller's email campaign performance report for a specified time period.View getEmailReport - /email_campaign/report
updateEmailCampaignPUT/email_campaign/{email_campaign_id}Updates an existing Store email campaign.View updateEmailCampaign - /email_campaign/{email_campaign_id}