# Marketing and Promotions Guide **Guide Group:** Marketing and Promotions --- ## Overview The Sell Marketing API allows sellers to manage and optimize their marketing efforts for their eBay listings, giving their products more visibility. Sellers can use the API methods to create Promoted Listings ad campaigns, create discount promotions, and create and send email campaigns. ## API Use Cases [Creating and managing Promoted Listings general strategy campaigns](#generalstrategycampaigns) [Creating and managing Promoted Listings priority strategy campaigns](#prioritystrategycampaigns) [Creating and managing Promoted Offsite campaigns](#offsitecampaigns) [Creating and retrieving Promoted Listings and Promoted Offsite reports](#listingspromotedoffsitereports) [Creating and managing discounts](#managingdiscounts) [Creating and retrieving discount reports](#discountreports) [Creating and managing a store email campaign](#storeemailcampaign) ##### Creating and managing Promoted Listings general strategy campaigns General strategy campaigns use the Cost Per Sale (CPS) funding model and leverage the eBay [Recommendation API](/api-docs/sell/recommendation/static/overview.html) to retrieve recommendations on which listings could benefit from a Promoted Listings campaign, as well as the trending bid percentages for the listings that will be promoted. There are two primary ways to create a general strategy campaign, each of which provide different methods for adding listings to the campaign: **key-based campaigns** and **rules-based campaigns**. Key-based campaigns allow sellers to manually add listings to a campaign, while rules-based campaigns select listings to add to the campaign based on a pre-defined set of listing criteria, such as a certain brand of an item.  The Sell Marketing API approaches used to create and manage a Promoted Listings general strategy campaign are discussed below: ![Banner image](/cms/img/sellmarketingpromotionsguide/pls.svg) 1. Create and set up the structure of a Promoted Listings campaign using [createCampaign](/api-docs/sell/marketing/resources/campaign/methods/createCampaign) and configure the following required fields. * [marketplaceId](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.marketplaceId) * [campaignName](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignName) * [startDate](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.startDate) 3. Set up the funding strategy for the general strategy campaign by configuring the following [fundingStrategy](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy) fields:  * \[required\] [bidPercentage](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.bidPercentage) * \[required\] [fundingModel](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.fundingModel) (set to COST\_PER\_SALE) * \[optional\]  [adRateStrategy](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.adRateStrategy)  5. Create a **rules-based** or **key-based** campaign: * To create a **key-based** campaign, manually add one or more active listings to an existing campaign using one of the following methods. With each of these four methods, the campaign ID is passed in as a path parameter. **Note:** The [findListingRecommendations](/api-docs/sell/recommendation/resources/listing_recommendation/methods/findListingRecommendations) method of **Recommendation API** can be used to retrieve recommendations for which listings will perform the best in your Promoted Listings campaign, as well as the trading bid percentages for these listings. * Use [bulkCreateAdsByListingId](/api-docs/sell/marketing/resources/ad/methods/bulkCreateAdsByListingId) or [createAdsByListingId](/api-docs/sell/marketing/resources/ad/methods/createAdByListingId) to add one or more listings to a Promoted Listings campaign using the unique identifier of the listing generated by the Trading API or Inventory API. * Use [bulkCreateAdsByInventoryReference](/api-docs/sell/marketing/resources/ad/methods/bulkCreateAdsByInventoryReference) or [createAdsByInventoryReference](/api-docs/sell/marketing/resources/ad/methods/createAdsByInventoryReference) to add one or more listings to a Promoted Listings campaign using the unique identifier of a single-item or multi-variation listing generated with the Inventory API. * To create a **rules-based** campaign, specify one or more of the [selectionRules](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules) criteria listed below, and listings that meet all specified criteria will be added to the campaign: **Note:** There is an [autoSelectFutureInventory](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.autoSelectFutureInventory) boolean that can be included and set to _true_ if the seller wants any future listings matching the criteria to be added to the campaign. * [brands](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules.brands)**:** An array of brand names are specified here, and listing with the products that have one of the brand names will be eligible to be added to the campaign. * [categoryIds](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules.categoryIds)**:** An array of eBay leaf category IDs or eBay Store category IDs are specified here, and listings in one of these eBay or eBay Store categories will be eligible to be added to the campaign. * [listingConditionIds](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules.listingConditionIds)**:** An array of eBay item condition IDs are specified here, and listings using one of these item conditions will be eligible to be added to the campaign. * [maxPrice](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules.maxPrice) and/or [minPrice](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules.minPrice)**:** A **minPrice** and/or **maxPrice** threshold may be added as criteria. The sale price of the item must be within these thresholds to be eligible to be added to the campaign. Below are the other methods applicable to managing general strategy campaigns: * Use [cloneCampaign](/api-docs/sell/marketing/resources/campaign/methods/cloneCampaign) to create a new campaign using an existing rules-based campaign’s specified campaign criterion.  * Use [updateAdRateStrategy](/api-docs/sell/marketing/resources/campaign/methods/updateAdRateStrategy) to update the ad rate strategy for an existing rules-based campaign. * Use [findCampaignByAdReference](/api-docs/sell/marketing/resources/campaign/methods/findCampaignByAdReference) to retrieve the campaigns containing a particular listing or listings, specified by a listing’s **listingId** or its seller-defined **SKU** or **inventoryItemGroupKey** value. * Use [updateBid](/api-docs/sell/marketing/resources/ad/methods/updateBid) to update the bid percentage (ad rate) for a specified ad in a general strategy campaign. * Use [deleteAd](/api-docs/sell/marketing/resources/ad/methods/deleteAd) or [deleteAdsByInventoryReference](/api-docs/sell/marketing/resources/ad/methods/deleteAdsByInventoryReference) to remove an ad from a specified campaign. * Use [getCampaign](/api-docs/sell/marketing/resources/campaign/methods/getCampaign), [getCampaigns](/api-docs/sell/marketing/resources/campaign/methods/getCampaigns), [getCampaignByName](/api-docs/sell/marketing/resources/campaign/methods/getCampaignByName), or  [findCampaignByAdReference](/api-docs/sell/marketing/resources/campaign/methods/findCampaignByAdReference) to retrieve details about one or more Promoted Listings Advertising campaigns. * Use [deleteCampaign](/api-docs/sell/marketing/resources/campaign/methods/deleteCampaign) to delete a specific Promoted Listings campaign.  * Use [pauseCampaign](/api-docs/sell/marketing/resources/campaign/methods/pauseCampaign) to pause an active campaign, and [resumeCampaign](/api-docs/sell/marketing/resources/campaign/methods/resumeCampaign) to resume a paused campaign.  * Use [endCampaign](/api-docs/sell/marketing/resources/campaign/methods/endCampaign) to end a running Promoted Listings campaign. ##### Creating and managing Promoted Listings priority strategy campaigns Priority strategy campaigns use the Cost-Per-Click (CPC) funding model and leverage the eBay Marketing API to retrieve suggestions for listings, keywords, and bids for the campaign. There are two primary ways to create a priority strategy campaign, each of which provides different methods for configuring the campaign: **Manual targeting campaigns** and **Smart targeting campaigns**. Manual targeting campaigns offer sellers complete control over campaign setup and optimization, while smart targeting campaigns offer easy setup and automatically optimize the campaign for the seller. The Sell Marketing API approaches used to create and manage Promoted Listings priority strategy campaigns are discussed below: **Manual targeting campaign** Manual targeting campaigns allow sellers to have complete control over the listings, keywords, and keyword bids associated with the campaign. ![Banner image](/cms/img/sellmarketingpromotionsguide/manual-setup.svg) 1. Create and set up the structure of a manual targeting campaign using [createCampaign](/api-docs/sell/marketing/resources/campaign/methods/createCampaign) and configure the following required fields: * [marketplaceId](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.marketplaceId) * [campaignName](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignName) * [Budget](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.budget) * [fundingStrategy.fundingModel](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.fundingModel) (set to COST\_PER\_CLICK) * [startDate](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.startDate) 3. Optionally, use [suggestItems](/api-docs/sell/marketing/resources/campaign/methods/suggestItems) to retrieve eBay suggested listings for a CPC Promoted Listings campaign. 4. Create an ad group for the campaign using [createAdGroup](/api-docs/sell/marketing/resources/ad_group/methods/createAdGroup) and specify the **defaultBid** value for the ad group. 5. Add listings to the ad group using [bulkCreateAdsByListingId](/api-docs/sell/marketing/resources/ad/methods/bulkCreateAdsByListingId) or [createAdsByListingId](/api-docs/sell/marketing/resources/ad/methods/createAdByListingId). 6. Optionally, use [suggestKeywords](/api-docs/sell/marketing/resources/ad_group/methods/suggestKeywords) to retrieve keyword recommendations for the ad group and its listings, and use [suggestBids](/api-docs/sell/marketing/resources/ad_group/methods/suggestBids) to see which bids are recommended for the specified keywords. 7. Use [bulkCreateKeyword](/api-docs/sell/marketing/resources/keyword/methods/bulkCreateKeyword) or [createKeyword](/api-docs/sell/marketing/resources/keyword/methods/createKeyword) to add keywords to the ad group, and optionally use [bulkCreateNegativeKeyword](/api-docs/sell/marketing/resources/negative_keyword/methods/bulkCreateNegativeKeyword) or [createNegativeKeyword](/api-docs/sell/marketing/resources/negative_keyword/methods/createNegativeKeyword) to add negative keywords to the ad group. **Smart targeting campaign** ![Banner image](/cms/img/sellmarketingpromotionsguide/smart-targeting.svg) 1. Optionally, use [suggestMaxCpc](/api-docs/sell/marketing/resources/campaign/methods/suggestMaxCpc) to retrieve the suggested maximum cost-per-click value (**maxCpc**) value for a smart targeting campaign, based on the specified listings and marketplace. 2. Create and set the structure of the smart targeting campaign using [createCampaign](/api-docs/sell/marketing/resources/campaign/methods/createCampaign) and configure the following required fields:  * [marketplaceId](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.marketplaceId) * [campaignName](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignName) * [fundingStrategy.fundingModel](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.fundingModel) (set to COST\_PER\_CLICK) * [fundingStrategy.bidPreferences.maxCpc](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.bidPreferences.maxCpc) * [campaignTargetingType](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignTargetingType) (set to SMART) * [startDate](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.startDate) 4. Add listings to the campaign using [createAdByListingId](/api-docs/sell/marketing/resources/ad/methods/createAdByListingId) or [bulkCreateAdsByListingId](/api-docs/sell/marketing/resources/ad/methods/bulkCreateAdsByListingId). Below are the other methods applicable to managing priority strategy campaigns: * Use [updateBiddingStrategy](/api-docs/sell/marketing/resources/campaign/methods/updateBiddingStrategy) to change the bidding strategy on a manual targeting CPC campaign from _Fixed_ to _Dynamic_, or vice versa. In addition, this method can be used to update the **maxCPC** value of a smart targeting campaign. * Use [updateCampaignBudget](/api-docs/sell/marketing/resources/campaign/methods/updateCampaignBudget) to modify the daily budget for a priority strategy campaign.  * Use [getCampaign](/api-docs/sell/marketing/resources/campaign/methods/getCampaign), [getCampaigns](/api-docs/sell/marketing/resources/campaign/methods/getCampaigns), [getCampaignByName](/api-docs/sell/marketing/resources/campaign/methods/getCampaignByName), or  [findCampaignByAdReference](/api-docs/sell/marketing/resources/campaign/methods/findCampaignByAdReference) to retrieve details about one or more Promoted Listings Advertising campaigns. * Use [deleteCampaign](/api-docs/sell/marketing/resources/campaign/methods/deleteCampaign) to delete a specific Promoted Listings campaign.  * Use [pauseCampaign](/api-docs/sell/marketing/resources/campaign/methods/pauseCampaign) to pause an active campaign, and [resumeCampaign](/api-docs/sell/marketing/resources/campaign/methods/resumeCampaign) to resume a paused campaign.  * Use [endCampaign](/api-docs/sell/marketing/resources/campaign/methods/endCampaign) to end a running Promoted Listings campaign. * Use [bulkUpdateAdsStatus](/api-docs/sell/marketing/resources/ad/methods/bulkUpdateAdsStatus) to update the status of ads in bulk. * Use [updateKeyword](/api-docs/sell/marketing/resources/keyword/methods/updateKeyword) and [bulkUpdateKeyword](/api-docs/sell/marketing/resources/keyword/methods/bulkUpdateKeyword) to update keyword bids and statuses. * Use [updateNegativeKeyword](/api-docs/sell/marketing/resources/negative_keyword/methods/updateNegativeKeyword) and [bulkUpdateNegativeKeywords](/api-docs/sell/marketing/resources/negative_keyword/methods/bulkUpdateNegativeKeyword) to update negative keyword bids and statuses. ##### Creating and managing Promoted Offsite campaigns Promoted Offsite campaigns give sellers the ability to reach a wider audience of potential buyers by promoting their listings on external channels and increasing visibility with interested buyers. The [Sell Marketing API](/api-docs/sell/marketing/resources/methods) approaches used to create and manage a Promoted Offsite campaign are discussed below: ![Banner image](/cms/img/sellmarketingpromotionsguide/offsite.svg) 1. Optionally, retrieve the suggested budget for a Promoted Offsite campaign using [suggestBudget](/api-docs/sell/marketing/resources/campaign/methods/suggestBudget)**.**  2. Create and set the structure of the Promoted Offsite campaign using [createCampaign](/api-docs/sell/marketing/resources/campaign/methods/createCampaign) and configuring the following required fields:  * [marketplaceId](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.marketplaceId)  * [campaignName](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignName)  * [fundingModel](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.fundingStrategy.fundingModel) (set to COST\_PER\_CLICK) * [channels](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.channels) (set to OFF\_SITE) * [startDate](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.startDate) Below are the other methods applicable to managing Promoted Offsite campaigns: * Use [getCampaign](/api-docs/sell/marketing/resources/campaign/methods/getCampaign), [getCampaigns](/api-docs/sell/marketing/resources/campaign/methods/getCampaigns), [getCampaignByName](/api-docs/sell/marketing/resources/campaign/methods/getCampaignByName), or  [findCampaignByAdReference](/api-docs/sell/marketing/resources/campaign/methods/findCampaignByAdReference) to retrieve details about one or more Promoted Listings Advertising campaigns. * Use [deleteCampaign](/api-docs/sell/marketing/resources/campaign/methods/deleteCampaign) to delete a specific Promoted Listings campaign.  * Use [pauseCampaign](/api-docs/sell/marketing/resources/campaign/methods/pauseCampaign) to pause an active campaign, and [resumeCampaign](/api-docs/sell/marketing/resources/campaign/methods/resumeCampaign) to resume a paused campaign. * Use [endCampaign](/api-docs/sell/marketing/resources/campaign/methods/endCampaign) to end a running Promoted Listings campaign. ##### Creating and retrieving Promoted Listings and Promoted Offsite reports The Marketing API provides sellers with the ability to create and retrieve reports about their Promoted Listings campaign and Promoted Offsite campaign performance. A variety of report types are available, such as **listing reports**, which offer a daily view of the performance of each listing in a campaign, or **keyword reports**, which provide keyword performance data for a specific campaign. For a full list of supported Promoted Listings report types, see [ReportTypeEnum](/api-docs/sell/marketing/types/plr:ReportTypeEnum). The [Sell Marketing API](/api-docs/sell/marketing/resources/methods) methods used to retrieve Promoted Listings and Promoted Offsite reports are discussed below: ![Banner image](/cms/img/sellmarketingpromotionsguide/promoted-listings-reports.svg) 1. Retrieve the fields required for each Promoted Listings report type using [getReportMetadata](/api-docs/sell/marketing/resources/ad_report_metadata/methods/getReportMetadata), or retrieve the required fields for a specific report type using [getReportMetadataForReportType](/api-docs/sell/marketing/resources/ad_report_metadata/methods/getReportMetadataForReportType). 2. Create a Promoted Listings report for one or more campaigns using [createReportTask](/api-docs/sell/marketing/resources/ad_report_task/methods/createReportTask).  Specify the type of report being created in the [reportType](/api-docs/sell/marketing/resources/ad_report_task/methods/createReportTask#request.reportType) field, as well as any other required fields based on the specified type.  3. Check the status of a Promoted Listings report using [getReportTasks](/api-docs/sell/marketing/resources/ad_report_task/methods/getReportTasks) or [getReportTask](/api-docs/sell/marketing/resources/ad_report_task/methods/getReportTask). Reports often take time to generate, and will not be available for download until their status is SUCCESS. 4. Download a Promoted Listings report using [getReport](/api-docs/sell/marketing/resources/ad_report/methods/getReport). ##### Creating and managing discounts Discounts Manager provides sellers with the ability to offer price discounts on an item's regular sales price. There are two primary discount types: **markdown discounts** and **threshold discounts**. Markdown discounts are a straightforward monetary or percentage discount off the price of a listing, while threshold discounts require the buyer to meet an established threshold (such as spending x amount) before the discount triggers. The [Sell Marketing API](/api-docs/sell/marketing/resources/methods) methods used to create and manage discounts are discussed below: **Item markdown discounts** ![Banner image](/cms/img/sellmarketingpromotionsguide/item-markdown.svg) 1. Create a markdown discount using [createItemPriceMarkdownPromotion](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion) and configure the following required fields:  * [marketplaceId](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.marketplaceId): The unique identifier of the site where the discount is hosted. * [discountBenefit](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.selectedInventoryDiscounts.discountBenefit): The monetary amount or percentage discount applied to the sales price. * [startDate](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.startDate) and [endDate](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.endDate): The start and end date of the discount. 3. Specify the items to be included in the discount by using either **rules-based** or **key-based** discounts:  * To create a **key-based** discount, set the [inventoryCriterionType](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.inventoryCriterionType) to _INVENTORY\_BY\_VALUE_, and specify the items to be included in the discount using one of the following arrays:  * [listingIds](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.selectedInventoryDiscounts.inventoryCriterion.listingIds): Use the unique identifier of a listing generated by the Trading API or the Inventory API to specify the listings you want to discount. * [inventoryItems](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.selectedInventoryDiscounts.inventoryCriterion.inventoryItems): Use the unique identifier of a single-item or multi-variation listing generated with the Inventory AP to specify the items you want to discount. * To create a **rules-based** discount, set the [inventoryCriterionType](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.inventoryCriterionType) to _INVENTORY\_BY\_RULE_, and specify one or more of the [selectionRules](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules) criteria listed below, and listings that meet all specified criteria will be added to the campaign:  * [Brand](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.brands) * [categoryIds](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.categoryIds) * [categoryScope](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.categoryScope) * [listingConditionIds](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.listingConditionIds) * [maxPrice](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.maxPrice) * [minPrice](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.minPrice) **Threshold discounts** ![Banner image](/cms/img/sellmarketingpromotionsguide/threshold-discount.svg) 1. Create a threshold discount using [createItemPromotion](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion) and configure the following required fields:  * [marketplaceId](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.marketplaceId): The unique identifier of the site where the discount is hosted. * [discountBenefit](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.selectedInventoryDiscounts.discountBenefit): The monetary amount or percentage discount applied to the sales price. * [startDate](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.startDate) and [endDate](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.endDate): The start and end date of the discount. 3. Specify the type of threshold discount through the [promotionType](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.promotionType) field. The following types of discounts can be created using this method: * **Coded Coupon:** The seller offers unique coupon codes that buyers can use during checkout to receive a discount.  * **Order Discount:** The seller offers an order discount based on the order size or the amount spent by the buyer. * **Volume Discount:** The seller offers a tiered discount to buyers who purchase multiple quantities of a single item. * **Markdown Discount:** A discount amount is applied directly to eligible items. 4. Input any required fields for the specified promotion type. For example, Coded Coupon promotions require the [couponConfiguration](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.couponConfiguration) container. Refer to the reference documentation for the required fields for each promotion type. 5. Specify the threshold discount rules by configuring the [discountSpecifications](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.discountRules.discountSpecification) field. This field defines a set of rules that determine when the discount is applied. The following rules can be set:  * [minAmount](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.discountRules.discountSpecification.minAmount)**:** The minimum dollar amount that needs to be spent on eligible items in order to qualify for the discount. * [minQuantity](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.discountRules.discountSpecification.minQuantity)**:** The minimum quantity of eligible items that needs to be bought in order to qualify for the discount. * [forEachQuantity](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.discountRules.discountSpecification.forEachQuantity)**:** The discount triggers each time the buyer spends the specified monetary amount on eligible items. * [forEachAmount](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.discountRules.discountSpecification.forEachAmount)**:** The discount triggers each time the buyer purchases the specified quantity of eligible items. 6. Specify the items to be included in the discount by using either **rules-based** or **key-based** discounts:  1. To create a **key-based** discount, set the [InventoryCriterionType](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.inventoryCriterionType) to _INVENTORY\_BY\_VALUE_, and specify the items to be included in the discount using one of the following arrays:  * [listingIds](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.selectedInventoryDiscounts.inventoryCriterion.listingIds): Use the unique identifier of a listing generated by the Trading API or the Inventory API to specify the listings you want to discount. * [inventoryItems](/api-docs/sell/marketing/resources/item_price_markdown/methods/createItemPriceMarkdownPromotion#request.selectedInventoryDiscounts.inventoryCriterion.inventoryItems): Use the unique identifier of a single-item or multi-variation listing generated with the Inventory AP to specify the items you want to discount. 3. To create a **rules-based** discount, set the [InventoryCriterionType](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.inventoryCriterionType) to _INVENTORY\_BY\_RULE_, and specify one or more of the [selectionRules](/api-docs/sell/marketing/resources/campaign/methods/createCampaign#request.campaignCriterion.selectionRules) criteria listed below, and listings that meet all specified criteria will be added to the campaign:  * [brand](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.brands) * [categoryIds](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.categoryIds) * [categoryScope](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.categoryScope) * [listingConditionIds](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.listingConditionIds) * [maxPrice](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.maxPrice) * [minPrice](/api-docs/sell/marketing/resources/item_promotion/methods/createItemPromotion#request.inventoryCriterion.ruleCriteria.selectionRules.minPrice) Below are the other methods applicable to managing item discounts: * Use [pausePromotion](/api-docs/sell/marketing/resources/promotion/methods/pausePromotion) and [resumePromotion](/api-docs/sell/marketing/resources/promotion/methods/resumePromotion) to pause or resume a discount. * Use [getListingSet](/api-docs/sell/marketing/resources/promotion/methods/getListingSet) to retrieve the set of listings associated with a discount. * Use [getPromotions](/api-docs/sell/marketing/resources/promotion/methods/getPromotions) to retrieve a list of discounts offered by a seller. * Use [deleteItemPriceMarkdownPromotion](/api-docs/sell/marketing/resources/item_price_markdown/methods/deleteItemPriceMarkdownPromotion) or [deleteItemPromotion](/api-docs/sell/marketing/resources/item_promotion/methods/deleteItemPromotion) to delete a discount that is no longer active. * Use [getItemPriceMarkdownPromotion](/api-docs/sell/marketing/resources/item_price_markdown/methods/getItemPriceMarkdownPromotion) or [getItemPromotion](/api-docs/sell/marketing/resources/item_promotion/methods/getItemPromotion) to retrieve the complete details of a specific discount. * Use [updateItemPriceMarkdownPromotion](/api-docs/sell/marketing/resources/item_price_markdown/methods/updateItemPriceMarkdownPromotion) or [updateItemPromotion](/api-docs/sell/marketing/resources/item_promotion/methods/updateItemPromotion) to update a discount with a new configuration. The parameters you are allowed to update with these methods depends on the status of the discount being updated. ##### Creating and retrieving discount reports Sellers can track the performance of their discounts using two types of discount reports: Promotion Summary reports and Promotion reports.  * Generate a report summarizing a seller’s discounts using [getPromotionSummaryReport](/api-docs/sell/marketing/resources/promotion_summary_report/methods/getPromotionSummaryReport). * Retrieve a list of all running, paused, or ended discounts using [getPromotionReports](/api-docs/sell/marketing/resources/promotion_report/methods/getPromotionReports). ##### Creating and managing a store email campaign Store email campaigns allow eBay Store owners to create and send email campaigns to subscribers, followers, and seller-defined buyer groups. Sellers can use campaigns to welcome customers, let them know about new promotions, sales, and discounts.  The basic flow to create email campaigns using the Sell Marketing API is covered below: ![Banner image](/cms/img/sellmarketingpromotionsguide/store-email-campaign.svg) 1. Retrieve all available audiences for a specific email campaign type by using [getAudiences](/api-docs/sell/marketing/resources/email_campaign/methods/getAudiences)**.** See [CampaignTypeEnum](/api-docs/sell/marketing/types/api:CampaignTypeEnum) for a list of all supported campaign types.  2. Create an email campaign using [createEmailCampaign](/api-docs/sell/marketing/resources/email_campaign/methods/createEmailCampaign), specifying the audience for the campaign through the [audienceCodes](/api-docs/sell/marketing/resources/email_campaign/methods/createEmailCampaign#request.audienceCodes) array and the type of email campaign through the [emailCampaignType](/api-docs/sell/marketing/resources/email_campaign/methods/createEmailCampaign#request.emailCampaignType) field. The following email campaign types are supported for email campaigns:  * **Welcome**: Automatically sent to new subscribers.  * **Item Showcase**: Can be sent to all subscribers, followers, or buyer groups and includes new products and collections the seller wishes to highlight. * **Coupon**: Sent to all subscribers, followers, recent buyers, or buyer groups, and includes a coupon code and up to four items this coupon can be applied to. * **Order Discount:** Sent to all subscribers, followers, recent buyers, or buyer groups, and contains can order discounts and up to ten items that this discount can be applied to. * **Sale Event**: Sent to all subscribers, followers, recent buyers, or buy groups, and contains a notice about a sale event and up to ten items that the sale can be applied to. * **Volume Pricing**: Sent to all subscribers, followers, recent buyers, or buyer groups, and contains items that are eligible for volume pricing.  4. Optionally, the [scheduleDate](/api-docs/sell/marketing/resources/email_campaign/methods/createEmailCampaign#request.scheduleDate) field can be used to set a time and date in the future for the email campaign to be sent out. Sellers can then retrieve a preview of the email campaign using [getEmailPreview](/api-docs/sell/marketing/resources/email_campaign/methods/getEmailPreview) before the campaign launches.  5. Use [getEmailReport](/api-docs/sell/marketing/resources/email_campaign/methods/getEmailReport) to retrieve performance data on all active email campaigns. The following are additional methods that can be used to manage store email campaigns * Use [getEmailCampaign](/api-docs/sell/marketing/resources/email_campaign/methods/getEmailCampaign) to retrieve full details on a specific campaign or [getEmailCampaigns](/api-docs/sell/marketing/resources/email_campaign/methods/getEmailCampaigns) to retrieve details on multiple campaigns of a specific type. * Use [updateEmailCampaign](/api-docs/sell/marketing/resources/email_campaign/methods/updateEmailCampaign) to update an existing email campaign. * Use [deleteEmailCampaign](/api-docs/sell/marketing/resources/email_campaign/methods/deleteEmailCampaign) to delete a specific email campaign. ## Code Samples ## Error Handling * If a Promoted Listings API call is failing due to an invalid **marketplaceId**, refer to the [Promoted Listings requirements and restrictions](https://developer.ebay.com/api-docs/sell/marketing/static/overview.html#PL-requirements) for the supported marketplaces, and ensure you pass the appropriate **marketplaceId** value in the API request. * If a Discounts Manager API call is failing due to an invalid **marketplaceId**, refer to the [Discounts Manager requirements and restrictions](https://developer.ebay.com/api-docs/sell/marketing/static/overview.html#PM-requirements) for the supported marketplaces, and ensure you pass the appropriate **marketplaceId** value in the API request. * If you receive an invalid category error when attempting to create a Promoted Listings campaign, verify the value of the category ID. Each marketplace has a select set of categories that support Promoted Listings. See [Category support by marketplace](https://developer.ebay.com/api-docs/sell/static/marketing/pl-supported-categories.html#Category) for a list of categories that support Promoted listings by marketplace. * If you receive an error stating that you are not eligible for promotions when creating a Discounts Manager discount or a Store Email Campaign, ensure that you have an active eBay store subscription.  * If you receive an error stating that you are not eligible to create a Promoted Listings campaign, ensure that you have accepted the terms and conditions for your marketplace. See [Supported marketplaces and seller requirements](https://developer.ebay.com/api-docs/sell/marketing/overview.html#PL-requirements) for links to the terms and conditions for each marketplace. * If you receive an error when attempting to create a Markdown discount, check how long the item has been listed at its current price. On certain marketplaces, items must be listed at the same price without being part of a sale for a set number of days before they can be included in a markdown discount. See [markdown discount listing requirements](https://developer.ebay.com/api-docs/sell/marketing/overview.html#PM-requirements) for a list of days that an item must be listed before it is eligible for an item price markdown discount. ## Best Practices * Use the [getAdvertisingEligibility](https://developer.ebay.com/api-docs/sell/account/resources/advertising_eligibility/methods/getAdvertisingEligibility)  method of the **Account API v1** to check a seller’s eligibility status for each eBay advertising program. * To gain access to the Promoted Listings priority advertising program, sellers must complete and submit an [Application Growth Check](https://developer.ebay.com/grow/application-growth-check). * Sellers using Promoted Listings can leverage the **Notification API** to receive account notifications for their campaigns by subscribing to the PLA\_CAMPAIGN\_BUDGET\_STATUS alert type for notifications regarding priority campaign updates. ## Code Samples ### Retrieve active Promoted Listings Priority campaigns **Label:** Retrieve active Promoted Listings Priority campaigns #### Bash Sample ```bash curl -X GET "https://api.ebay.com/sell/marketing/v1/ad_campaign?campaign_status=RUNNING&funding_strategy=COST_PER_CLICK" -H "Authorization:Bearer OAUTH_token" ``` ### Retrieve active order discounts for US marketplace **Label:** Retrieve active order discounts for US marketplace #### Bash Sample ```bash curl -X GET "https://api.ebay.com/sell/marketing/v1/promotion?marketplace_id=EBAY_US&promotion_status=RUNNING&promotion_type=ORDER_DISCOUNT" -H "Authorization:Bearer OAUTH_token" ``` ## Related Topics - [Sell Marketing API](/api-docs/sell/marketing/overview.html) - [Promoted Listings Playbook](/api-docs/sell/static/marketing/pl-landing.html) - [More Guides](/develop/guides)