Creating a Promoted Listings campaign

In a nutshell, you use createCampaign to create the structure for a new Promoted Listings campaign. A campaign by itself, however, is not enough to promote your listings. You need to indicate which of your listings you want to promote, then create ads for those listings.

Subtopics

Which one: rules-based vs. key based campaigns

There are two ways to create Promoted Listings campaigns and add listings them:

  • Rules-based ads select listings to include in a campaign using a set of criteria, or rules, that you specify in a call to createCampaign. The rules you create 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 ads 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 the following keys:

    • 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's managed by the Inventory API.

You can include ads for up to 50,000 items in any one campaign, and each item in a multiple-variation listing counts as an individual item.

Also, 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 running Promoted Listings campaign at a time.

Creating a rules-based campaign

The quickest way to create a campaign and add listings to it is to create a rules-based campaign using a single call to createCampaign.

Configuring the structure of a campaign

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

  • marketplaceId – The eBay marketplace on which the campaign runs.
  • campaignName – The campaign name is a seller-defined name given to the campaign.
  • fundingStrategy – The funding strategy is a combination of the bidPercentage and the fundingModel used for the campaign.

    The bidPercentage (also know as the ad rate) sets the level to which you want to promote the items in your campaign (see the Promoted Listings topic for details). The fundingModel is the mechanism used to calculate the Promoted Listing fee, and currently only COST_PER_SALE is supported.

  • startDate – The start date sets the day on which the campaign begins. Optionally, you can also set the endDate for the campaign.
{
  "marketplaceId": "EBAY_US",
  "campaignName": "Wedges promotion",
  "fundingStrategy": {
    "bidPercentage": "3.5",
    "fundingModel": "COST_PER_SALE"
  },
  "startDate": "2019-06-30T19:00:00Z",
  "endDate": "2019-07-30T19:00:00Z"
}

Important! The bidPercentage is always set at the ad level, and ads that are created by a rules-based campaign inherit their bidPercentage settings from the value configured in the createCampaign call. To modify the bidPercentage of an ad, call updateBid.

Adding items to a rules-based campaign

After configuring the structure of the campaign, identify the listings you want to include in the campaign by configuring the fields in the campaignCriterion.selectionRules object.

You can configure up to 10 distinct selectionRules elements, 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 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. See the Marketing API Reference for details on allowed values.
  • maxPrice – With all other rules considered, the price of a listing cannot exceed this amount for it to be included in the campaign.
  • minPrice – With all other rules considered, the price of a listing cannot be lower than this amount for it to be included in the campaign.
{
  "selectionRules": [
      {
        "brands": [ "list", "of", "brands"
        ],
        "categoryIds": [ "324490516", "324480516"
        ],
        "categoryScope": "STORE",
        "listingConditionIds": [ "300"
        ],
        "minPrice": {
          "currency": "USD",
          "value": "95.95"
        }
      }
    ]
  }

Important! You can specify listing-selection rules only when you first create a campaign with a request to createCampaign; you cannot update the selection rules in an existing campaign. If you need to change the rules that you've specified for a campaign, delete the existing campaign before creating a new campaign with the new selection rules. This is required because items can be included in only one campaign at a time.

When you submit a createCampaign call containing selection rules, the service checks the number of listings that comply with the rules. If the number of listings is <= 50,000, the request succeeds and ads are created for all 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.

Note that if the seller adds inventory after the initial createCampaign call, either before the campaign start date or during the time the service is creating ads, which results in a 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.

Note: When you create a campaign, the URI to the newly created campaign is returned in the Location response header. This value includes the campaign ID value.

Creating a campaign and including ads using listing IDs

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

An eBay listing ID can be either the listing ID that is created when you list an item with the Trading API, or the listing ID that's returned when you publish an "offer" with the Inventory API.

You add listings by ID to a campaign after you create and configure the campaign with a call to createCampaign. You then use the campaign ID to create the ads for the campaign.

Configuring the structure of a campaign

Call createCampaign to set up the structure of the campaign by configuring the following fields:

  • marketplaceId – The eBay marketplace on which the campaign runs.
  • campaignName – The campaign name is a seller-defined name given to the campaign.
  • fundingStrategy – The funding strategy is a combination of the bidPercentage and the fundingModel used for the campaign.

    The bidPercentage (also know as the ad rate) sets the level to which you want to promote the items in your campaign (see the Promoted Listings topic for details). The fundingModel is the mechanism used to calculate the Promoted Listing fee, and currently only COST_PER_SALE is supported.

    Note that bidPercentage rates are always set at the ad level, and that when you create ads for your campaign, the bidPercentage set by ID override the value that's set at the campaign level.

  • startDate – The start date sets the day on which the campaign begins. Optionally, you can also set the endDate for the campaign.
{
  "marketplaceId": "EBAY_US",
  "campaignName": "Wedges promotion",
  "fundingStrategy": {
    "bidPercentage": "3.5",
    "fundingModel": "COST_PER_SALE"
  },
  "startDate": "2019-06-30T19:00:00Z",
  "endDate": "2019-07-30T19:00:00Z"
}

Note: When you create a campaign, the URI to the newly created campaign is returned in the Location response header. This value includes the campaign ID value.

Using the Recommendation API for guidance

The Recommendation API offers recommendations on which listings will perform best by placing them in a Promoted Listings campaign, as well as returning the trending bid percentage for the listings you want to promote.

The recommendations offered by the Recommendation API can help you determine which listing to promote and how to configure your ads. For details, see Using the Recommendation API to help configure campaigns.

Creating ads using listing IDs

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

POST /sell/marketing/v1/ad_campaign/{ campaignId }/bulk_create_ads_by_listing_id
{
    "requests": [
        {
            "bidPercentage": "10.0",
            "listingId": "12000332930015"
        },
        {
            "bidPercentage": "7.5",
            "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 bulkCreateAdsByListingId 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 running Promoted Listings campaign at a time.

Creating a campaign and including ads 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's 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 differences are (1) you cannot use the Recommendation API with inventory reference IDs (the API currently works with only listing IDs) and (2) you use createAdByReferenceId to create individual ads for the campaign, or bulkCreateAdsByReferenceId to create ads in bulk.