Promoted Listings Advanced campaign flow

Promoted Listings Advanced (PLA) campaigns are created using key-based campaign criterion. Key-based campaigns use ID values and ad groups 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.
• Ad groups, which are created to gather listings and specify keywords that are used to search for and view the listings that you want to promote.

Key-based PLA campaigns

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 PLA campaigns using the Cost Per Click (CPC) funding model:

Using the key-based PLA campaign flow, you will complete the following steps to create and configure a PLA campaign:

1. Create the PLA campaign
2. Create an ad group for the PLA campaign
3. Create ads for the PLA campaign using listing IDs
4. Create keywords for the PLA campaign
5. Create negative keywords for the PLA campaign

Create the PLA 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 – The fundingModel used for the campaign. The fundingModel defines the mechanism used to calculate the Promoted Listing fee (see the Promoted Listings overview for details).
• budget – The allocated daily budget amount for PLA campaigns.
• 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 PLA campaign:

{
  "marketplaceId": "EBAY_US",
  "campaignName": "W***********n",
  "fundingStrategy": {
    "fundingModel": "COST_PER_CLICK"
  },
  "budget": {
    "daily": { 
      "amount": { 
        "currency": "USD",
        "value": "100.00"
      }
    } 
  },
  "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 an ad group for the PLA campaign

After creating a PLA campaign that uses the CPC funding model, you must create an ad group for listings that you want included in the campaign. Ad groups are used to gather listings and keywords.

To create an ad group for a campaign, specify the defaultBid for the ad group in the payload of the createAdGroup request, and specify the campaign to which the ad group should be associated using the campaign_id path parameter. The default bid amount applies to all of the keywords in an ad group that do not have individual bids specified (see the Create keywords section for details).

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/ad_group
{ /* CreateAdGroupRequest */
  "defaultBid" :
    { /*Amount*/
      "currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
      "value" : "string"
    },
  "name" : "string"
}

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

Each ad group can be associated with only one Promoted Listings campaign. Listings can be included across ad groups and can be in multiple active campaigns.

Create ads for the PLA 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 500 listings per call).

Specify the campaign to which the listings should be added using the campaign_id path parameter. You must also specify the adGroupId at this time.

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

Create keywords for the PLA campaign

After creating an ad group for the PLA campaign, you can create keywords that you want included in the ad group by calling the createKeyword method (to create one keyword) or the bulkCreateKeyword method (to create multiple keywords) to add the keyword(s) to the ad group.

Specify the campaign and ad group to which the keyword(s) should be added using the campaign_id path parameter and the adGroupId field.

Optionally, you can specify the bid amount for the keyword at this time. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount (see the Promoted Listings overview for details). If no bid amount is specified, the defaultBid amount defined for the ad group will apply.

Consider the keyword text carefully. When users search for items using the keywords that you have created, your Promoted Listings campaign ads will be considered for display.

Keywords are currently targeted using either exact match (with variants), phrase match, or broad match.

POST https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/keyword
{ /* CreateKeywordRequest 
  "adGroupId" : "string",				
  "bid" :
    { /*Amount*/
      "currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
      "value" : "string"
    },
  "keywordText" : "string",
  "matchType" : "MatchTypeEnum : [EXACT, PHRASE, BROAD]"
}

matchType targets

As mentioned above for keywords, matchType will support exact, phrase, and broad matching:

• EXACT: Exact match definition and examples can be found here.
• PHRASE: Phrase match definition and examples can be found here.
• BROAD: Broad match definition and examples can be found here.

As of 9/30/2022, BROAD match is available as a MatchTypeEnum for keywords to UI and API sellers in the US, UK, DE, IT, AU, FR. By 4/25/2023, it will be available to 100% of PLA-eligible site traffic.

Request example

{
  "keywordText": "Sony F1.8 85mm",
  "matchType": "BROAD",
  "adGroupId": "5000395516",
  "bid": {
    "value": "0.66",
    "currency": "USD"
  }
} 

Create negative keywords for the PLA campaign

After creating an ad group for the PLA campaign, you can create negative keywords that you want included in the ad group by calling the createNegativeKeyword method (to create one negative keyword) or the bulkCreateNegativeKeyword method (to create multiple negative keywords) to add the negative keyword(s) to the ad group.

Negative keywords are used to specify the search criterion that should not trigger listings in an ad group, which helps prevent your PLA campaigns from surfacing unnecessarily when buyers run keyword searches that do not apply to your listings.

Specify the campaign and ad group to which the negative keyword(s) should be added using the campaignId and the adGroupId request fields, and input the text for the negative keyword using the negativeKeywordText field.

POST https://api.ebay.com/sell/marketing/v1/negative_keyword
{ /* CreateNegativeKeywordRequest */
  "adGroupId": "string",
  "campaignId": "string",
  "negativeKeywordMatchType": "NegativeKeywordMatchTypeEnum: [EXACT]",
  "negativeKeywordText": "string"
}

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, ad groups, and keywords, and it outlines the system limitations for creating campaigns: 

• The suggestItems method allows sellers to retrieve ideas for listings that can be targeted for Promoted Listings campaigns. The recommendations provided by this method indicate listings that have a high chance of favorable performance based on historical data.
• The suggestKeywords method allows sellers to retrieve a list of keyword ideas to be targeted for Promoted Listings campaigns.
• The suggestBids method allows sellers to retrieve the suggested bids for input keywords and match type.

Quick Setup campaign flow

Quick setup is a way to easily create a Promoted Listings Advanced campaign. With quick setup, a seller sets their daily budget, chooses start and end dates, selects listings, and then eBay handles the rest of the campaign setup. When using quick setup, a seller can review and edit campaign details before launch.

Quick Setup as a value-add to your Promoted Listings Campaigns

Quick setup helps simplify the campaign creation process. Quick setup organizes listings into recommended ad groups. Once listings are sorted into ad groups, eBay selects keywords, keyword match types, and initial competitive keyword bids that we calculate will perform well.

Quick setup expedites creating initial Promoted Listings Advanced campaign settings using the Sell Marketing API, which would otherwise be set up manually in the campaign creation flow. Once a Promoted Listings Advanced campaign is launched with quick setup, sellers can monitor their campaign performance within the dashboard or Promoted Listings reporting and make ongoing optimizations to remain competitive.

Creating your Promoted Listings Advanced quick setup campaign

There are two required endpoints used to build the quick setup API experience.

1. setupQuickCampaign creates the PLA quick setup campaign and automatically saves it as a draft

2. launchCampaign launches the draft campaign

Required Step 1: Create Promoted Listings Advanced quick setup campaign draft

Request Payload code example

POST: https://api.ebay.com/sell/marketing/v1/ad_campaign/setup_quick_campaign

{
  "campaignName": "Spring Sale",
  "startDate": "2023-07-14T19:46:01.000Z",
  "endDate": "2023-09-07T01:02:35.000Z",
  "marketplaceId": "EBAY_US",
  "budget": {
    "daily": {
      "amount": {
        "value": "5.0",
        "currency": "USD"
      }
    }
  },
  "listingIDs": [
    "2********1"
  ]
}

With a successful setupQuickCampaign Marketing API method call, the campaignId as well as the getCampaign URI used to retrieve the newly-created campaign draft are returned in the response header. Sellers can optionally use this campaignId to call the getAdGroups, getAds, and getKeywords endpoints, and review the campaign structure before launching the campaign. These endpoints can be found in our Marketing API resources.

The listingIds are sent in the initial request payload to setupQuickCampaign as part of the campaign creation step. This is different from the createCampaign method, where sellers create an empty structure and then add listingIds to the ad groups after setup.

The maximum number of listings that can be added to a campaign is 1,000 listingIds.

Required Step 2: Launch Promoted Listings Advanced quick setup campaign draft

POST: https://api.ebay.com/sell/marketing/v1/ad_campaign/{campaign_id}/launch

To launch the draft campaign, call the above launchCampaign endpoint, using the campaignID returned in the response header. No additional payload parameters are required.