Promoted Listings Standard campaign flow

There are two primary ways to create Promoted Listings Standard (PLS) campaigns, each of which provide different flows and methods for the configuration of campaign criterion to add listings:

• Rules-based campaigns select listings to include in a campaign using a set of criteria, or rules, that you specify using the createCampaign method. The rules that you create are used to select listings based on a combination of brands, category IDs, item conditions, and the minimum and maximum prices of the listings you want to promote.

• Key-based campaigns use ID values to select the listings to include in a campaign. You can add listings to a campaign one at a time or in bulk using:

  • Listing ID values, which are created by the Trading API or Inventory API when you list an item.
  • Inventory reference ID and inventory reference type pairs, which together identify an item that is managed by the Inventory API.

Rules-based PLS campaigns

The quickest way to create a campaign and add listings is to create a rules-based campaign using the createCampaign method, where you will: 

1. Configure the PLS campaign structure
2. Add items to the PLS campaign

Configure the PLS campaign structure

In your call to the createCampaign method, set up the structure of the campaign by configuring the following fields:

• marketplaceId – The eBay marketplace for which the campaign will run.
• campaignName – The seller-defined name given to the campaign.

• fundingStrategy – A combination of the bidPercentage and the fundingModel used for the campaign. The bidPercentage (also known as the ad rate) defines the level at which you want to promote the items in your campaign (see the Promoted Listings overview for details). For rules-based campaigns, set the fundingModel to COST_PER_SALE.

• startDate – The day on which the campaign will begin.
• endDate – The day on which the campaign will end (this is an optional field).

Here is an example request payload that shows how to configure the structure of a CPS Promoted Listings campaign:

{
  "marketplaceId": "EBAY_US",
  "campaignName": "W**********n",
  "fundingStrategy": {
    "bidPercentage": "3.5",
    "fundingModel": "COST_PER_SALE"
  },
  "startDate": "2019-06-30T19:00:00Z",
  "endDate": "2019-07-30T19:00:00Z"
}

Add items to the PLS campaign

After configuring the structure of the campaign (and before submitting your createCampaign call), identify the listings that you want to include in the campaign by configuring the campaignCriterion data, including the selectionRules fields.

Up to ten distinct selectionRules elements can be configured, where each identifies a set of criteria for the listings to include in the campaign. When a listing matches all the rules you define, the Promoted Listings service creates an ad for that listing and includes the ad in the campaign. In each selectionRules element, configure the following fields to set up the criteria by which the ads are created:

• brands – A list of brands to include in the campaign. An ad is created for a listing if its brand matches one of the names identified in this rule.
• categoryIds – A list of category IDs, which can contain either category IDs from the associated marketplace or category IDs from the seller's store.
• categoryScope – A value that identifies the type of category IDs used in this set of rules, either MARKETPLACE or STORE.
• listingConditionIds – A list of numeric values that indicates the condition of the items to include in the campaign. The following values are currently supported:
  • 1000 – This value indicates that the listing condition is New. This includes listings that are:
    • New
    • New other (see details)
    • New - open box
    • New with defects
    • New with tags
    • New without tags
    • New with box
    • New without box
    • Brand new
    • New/Factory sealed
  • 2000 – This value indicates that the listing condition is Certified Refurbished.
  • 2500 – This value indicates that the listing condition is Seller Refurbished. This includes listings that are:
    • Seller refurbished
    • Remanufactured
    • Excellent - Refurbished
    • Very good - Refurbished
    • Good - Refurbished
  • 3000 – This value indicates that the listing condition is Used. This includes listings that are:
    • Used
    • Used - like new
    • Used - very good
    • Used - good
    • Used - acceptable
    • Used - fair
    • Pre-owned
    • For parts or not working
• maxPrice – The maximum price of listings that shall be included in the campaign.
• minPrice – The minimum price of listings that shall be included in the campaign.

You can set the autoSelectFutureInventory request field to true so that after your campaign launches, eBay will regularly assess your new, revised, or newly-eligible listings to determine whether any should be added or removed from your campaign according to the rules you set. If there are, eBay will add or remove them automatically on a daily basis when the following scenarios occur: 

• A new listing is created.
• An existing listing is revised.
• Another campaign ends, and the listings are released from the campaign.

Here is an example request payload that shows how to configure rules and add items to a CPS Promoted Listings campaign:

{
  "autoSelectFutureInventory": "true",
  "selectionRules": [
    {
      "brands": [  
        "list",   
        "of",  
        "brands"
      ],
      "categoryIds": [ 
        "list", 
        "of", 
        "category IDs"
      ],
      "categoryScope": "STORE",
      "listingConditionIds": [ 
        "list", 
        "of", 
        "listing condition IDs"
      ],
      "minPrice": {
        "currency": "USD",
        "value": "95.95"
      }
    }
  ]
}

When you submit the call containing selection rules to the createCampaign method, the service checks the number of listings that comply with the rules, and ads are created as follows: 

• If the number of listings is less than or equal to 50,000, the request is successful and ads are created for all of the items that match the selection rules (keep in mind that an ad is created for each item in a multiple-variation listing).
• If your rules result in the selection of more than 50,000 items, ads are created for only the first 50,000 items found, in order of recency.
• If a seller adds inventory after the initial call to the createCampaign method, either before the campaign start date or while the service is creating ads, and it results in greater-than 50,000 items matching the ad criteria, the service creates ads for only the first 50,000 items that match the specified selection rules.
• If you submit the call with the autoSelectFutureInventory request field to true, and no listings match your rules, the campaign can still be launched, and eBay will regularly check for listings that match your rules.

Key-based PLS campaigns

This section describes how to create a key-based campaign using listing IDs and reference IDs to identify the listings for which you want to create ads.

You add listings to a key-based campaign after you create and configure the campaign with a call to the createCampaign method. You then use the campaign ID that is returned in the Location response header to create the ads for the campaign.

The following diagram illustrates the creation flow for Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model:

As shown in the above chart, in order to create a key-based PLS campaign, you will: 

1. Create the PLS campaign
2. Create ads for the PLS campaign using:
   • Listing IDs
   • Reference IDs

Create the PLS campaign

Submit a call to the createCampaign method and configure the following fields:

• marketplaceId – The eBay marketplace for which the campaign will run.
• campaignName – The seller-defined name given to the campaign.
• fundingStrategy – A combination of the bidPercentage and the fundingModel used for the campaign. The bidPercentage defines the level at which you want to promote the items in your campaign, and the fundingModel defines the mechanism used to calculate the Promoted Listing fee (see the Promoted Listings overview for details).
• startDate – The day on which the campaign will begin.
• endDate – The day on which the campaign will end (this is an optional field).

Here is an example request payload that shows how to create a PLS campaign:

{ 
  "marketplaceId": "EBAY_US",
  "campaignName": "W**********n",
  "fundingStrategy": {
    "bidPercentage": "3.5",
    "fundingModel": "COST_PER_SALE"
  },
  "startDate": "2019-06-30T19:00:00Z",
  "endDate": "2019-07-30T19:00:00Z"
}

When you create a campaign, the URI to the newly created campaign is returned in the Location response header. This response includes the campaign ID value that is used to create ads and add them to the Promoted Listings campaign (see the sections below for details).

Create ads for the PLS campaign using listing IDs

After creating a campaign, you can create ads for the listings you want included in the campaign by calling either the createAdByListingId method (to add individual listing IDs) or the bulkCreateAdsByListingId method (to specify up to 50,000 listings per call).

Specify the campaign to which the listings should be added using the campaign_id path parameter. You can specify the bidPercentage (optional) at this time also.

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_Id}/bulk_create_ads_by_listing_id
{
  "requests": [
    {
      "bidPercentage": "{bidPercentage}",
      "listingId": "{listingId}"
    },
    {  
      "bidPercentage": "{bidPercentage}",
      "listingId": "{listingId}"
    }
  ]	
}

Each campaign can have ads for a maximum of 50,000 items, and multiple-variation listing IDs create an ad for each variation in the listing. If a call to the bulkCreateAdsByListingId method would generate more than 50,000 ads for a campaign, ads are created for only the first 50,000 items.

Be aware that each listing can be associated with just one ad and that each ad can be associated with only a single campaign. Listings cannot be associated with more than a single active PLS campaign at a time.

Create ads for the PLS campaign using reference IDs

If you manage your inventory with the Inventory API, you can use inventory reference IDs to create the ads for your campaign.

An inventory reference ID denotes a value that's used in the Inventory API. It can be either a seller-defined SKU value or an inventoryItemGroupKey (a seller-defined ID for a multiple-variation listing). You must pair each inventory reference ID with its associated inventory reference type (either INVENTORY_ITEM or INVENTORY_ITEM_GROUP) to indicate whether the listing is for a single item or it is for a multiple-variation listing.

The process for creating campaigns and including ads in the campaign using reference IDs is essentially the same as the process defined above for creating campaigns and using listing IDs to create ads. The main difference is that you use the createAdsByInventoryReference method to create individual ads for the campaign, or the bulkCreateAdsByInventoryReference method to create ads in bulk.

Campaign recommendations and suggestions

The eBay APIs allow you to retrieve recommendations and suggestions that you can use to configure your campaigns, such as listings, ad rates, and bid percentages, and it outlines the system limitations for creating campaigns: 

The Recommendation API offers recommendations on which listings will perform the best in a Promoted Listings campaign, as well as returning the trending bid percentage for the listings you want to promote. Note that you cannot use the Recommendation API with inventory reference IDs (the API currently works with only listing IDs).

Using the recommendation API to help configure campaigns

The findListingRecommendations method returns the following response body for each returned listingId:

"listingRecommendations": [{
  "listingId": "{listingId}",
  "marketing": {
    "ad": {
      "bidPercentages": [{
        "basis": "TRENDING",
        "value": "{trendingAdRate}"
      }],
      "promoteWithAd": "[RECOMMENDED || UNDETERMINED]"
    },
    "message": "string"
  }
}]

The above response body shows that findListingRecommendations returns two different recommendations for currently listed items:

• promoteWithAd – This response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign.
• bidPercentages – Also known as the "ad rate," the bid percentage field provides the current trending bid percentage of similarly promoted items in the marketplace.

The promoteWithAd indicator

When and how promoteWithAd is returned depends on how you structure your findListingRecommendations request.

If returned, promoteWithAd returns either RECOMMENDED or UNDETERMINED for any specific listing.

RECOMMENDED means that by eBay's calculations, the listing has highest potential of benefiting from being included in a Promoted Listings ad campaign.

This recommendation is determined by reviewing current marketplace trends, such as buyer demand and the competition in the item’s category, and eBay suggests you promote the RECOMMENDED listings first, although you can promote any of your eligible listings for greater visibility.

UNDETERMINED means eBay cannot determine the level of advantage gained by including the associated listing in an ad campaign.

The bidPercentage value

The bidPercentages field returns the current TRENDING "ad rate," which is calculated by averaging the ad rates of the listings that recently sold within the same category as the associated listing.

While eBay does not recommend the returned trending bid percentage as the optimum ad rate for your listing, you should consider this trending rate as a guide for how you set your own bidPercentage values.

Structuring a findListingRecommendations request

You can structure your findListingRecommendations requests to return recommendations for all of a seller's listings, or just the recommendations for a specific subset of the seller's listings.

In either case, the response is paginated to account for multiple returned listing IDs.

Getting recommendations for all of a seller's listings

If you do not include a request payload when you call findListingRecommendations, all of a seller's currently listed items are evaluated for recommendations. However, when all of a seller's listed items are considered, the request returns only those listings where promoteWithAd is set to RECOMMENDED.

If the promoteWithAd value is returned, the currently trending ad rate for each listing ID is also returned in the bidPercentages container.

For this request, set up the request headers then call the endpoint. All the query parameters are optional. If set, filter must be set to filter=recommendationTypes:{AD}, and you can use the limit and offest parameters to control the pagination of the response:

POST https://api.ebay.com/sell/recommendation/v1/find?
  filter=string&
  limit=integer&
  offset=integer

Getting recommendations for a select set of listings

You can call findListingRecommendations with a set of up to 500 specific listing IDs. Structure your request with a payload similar to the following example, where you separate each listingId value you specify with a comma:

{
  "listingIds": [
    "260011362444", "260011362546", "260011362826"
  ]
}

With a few exceptions (such as the listing is already in a Promoted Listings campaign or the listing is not eligible to be in a campaign), eBay returns recommendations for all supplied listingId values. And again, the trending bid percentage is included with each returned ID.

The promoteWithAd value of either RECOMMENDED or UNDETERMINED is also returned for all listings, except for those listings that are currently being promoted. In cases where a listing ID is already being promoted, the bidPercentages container is returned, but the promoteWithAd field is not returned.