marketing APIv1.8.0

createCampaign

POST
/ad_campaign
This method creates a Promoted Listings ad campaign.

A Promoted Listings campaign is the structure into which you place the ads for the listings you want to promote.

Identify the items you want to place into a campaign either by "key" or by "rule" as follows:

  • Rules-based campaigns – A rules-based campaign adds items to the campaign according to the criteria you specify in your call to createCampaign.
  • Key-based campaigns – Add items to an existing campaign using either listing ID values or Inventory Reference values:
    • Add listingId values to an existing campaign by calling either createAdByListingID or bulkCreateAdsByListingId.
    • Add inventoryReference values to an existing campaign by calling either createAdByInventoryReference or bulkCreateAdsByInventoryReference.

Note: No matter how you add items to a Promoted Listings campaign, each campaign can contain ads for a maximum of 50,000 items.

If a rules-based campaign identifies more than 50,000 items, ads are created for only the first 50,000 items identified by the specified criteria, and ads are not created for the remaining items.

Creating a campaign

To create a basic campaign, supply:

  • The user-defined campaign name
  • The start date (and optionally the end date) of the campaign
  • The eBay marketplace on which the campaign is hosted
  • Details on the campaign funding model

The campaign funding model specifies how the Promoted Listings fee is calculated. Currently, the only supported funding model is COST_PER_SALE. For complete information on how the fee is calculated and when it applies, see Promoted Listings fees.

If you populate the campaignCriterion object in your createCampaign request, campaign "ads" are created by "rule" for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign.

For details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see Creating a Promoted Listings campaign.

For recommendations on which listings are prime for a Promoted Listings ad campaign and to get guidance on how to set the bidPercentage field, see Using the Recommendation API to help configure campaigns.

Tip: See Promoted Listings requirements and restrictions for the details on the marketplaces that support Promoted Listings via the API.

Input

Resource URI (production)

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

URI parameters

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.marketing

See OAuth access tokens for more information.

Input container/fieldTypeDescription
campaignCriterionCampaignCriterionContainer for the fields that define the criteria for a rule-based campaign.

Occurrence: Optional

campaignCriterion.autoSelectFutureInventorybooleanReserved for future use.

Occurrence: Optional

campaignCriterion.criterionTypeCriterionTypeEnumThis enum defines the criterion (selection rule) types. Currently, the only criterion type supported is INVENTORY_PARTITION, and you must specify this value if you manage your items with the Inventory API and you want to include items based on their inventory reference IDs.

Leave this field blank if you want to create campaign ads based on listing IDs.

Occurrence: Optional

campaignCriterion.selectionRulesarray of SelectionRuleSet of rules that selects the listings to include in the campaign.

The following rules apply to the selection rules:

  • Each set of selection rules are ORed with each other.
  • Individual rules within a selection rule set are ANDed with each other. If a rule has a list of values (such a list of category IDs), the item need match only one of the values of the rule in order to be included in the campaign.
  • Note: If an item matches multiple sets of rules or multiple rules within a selection rule set, the item is considered only once.

Maximum number of rules: 10

Occurrence: Optional

campaignCriterion.selectionRules.brandsarray of stringA list of the brands of the items to be included in the campaign.

Occurrence: Optional

campaignCriterion.selectionRules.categoryIdsarray of stringA list of category IDs associated with the listings to be included in the campaign. Ada are created for all the seller's items listed in the specified categories, up to a maximum of 50,000 items. The IDs can be either a list of eBay category IDs (from the site where the item is hosted), or a list of category IDs defined and used by the seller's store.

eBay Marketplace category IDs
To get a list of marketplace category IDs, do one of the following:

  • Get a list of category IDs for a marketplace by adding /sch/allcategories/all-categories to the marketplace URL when browsing the site.
    For example: http://www.ebay.com.au/sch/allcategories/all-categories
  • Navigate to the desired category on the host site and copy the category ID from the URL.
  • These options are also available for the US marketplace:

Seller store category IDs
Because store category IDs are uniquely defined and maintained by each seller, this service cannot provide a list of a seller's IDs. However, sellers can retrieve their store category IDs as follows:

  1. Go to Seller Hub > Marketing.
  2. Click Manage store categories.
    A list of your store categories displays.
  3. Click the All categories link displayed at the bottom of the list.
    A complete list of your store categories and their associated store category IDs displays.

Occurrence: Optional

campaignCriterion.selectionRules.categoryScopeCategoryScopeEnumIndicates the source of the category ID; eBay or seller's store.

Occurrence: Optional

campaignCriterion.selectionRules.listingConditionIdsarray of stringThe ID of the listing's condition.

Note: In the US and Australian marketplaces, Condition ID 2000 now maps to an item condition of 'Certified Refurbished', but this item condition is only available for use for a select number of US and Australian sellers. For all other marketplaces besides the US and Australia, Condition ID 2000 still maps to 'Manufacturer Refurbished'.

Valid values:
  • 1000 = New
  • 2000 = Manufacturer refurbished
  • 2500 = Seller refurbished
  • 3000 = Used/Like new/Pre owned

Occurrence: Optional

campaignCriterion.selectionRules.maxPriceAmountThe maximum price of the listings included in the campaign.

Occurrence: Optional

campaignCriterion.selectionRules.maxPrice.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Optional

campaignCriterion.selectionRules.maxPrice.valuestringThe monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaignCriterion.selectionRules.minPriceAmountThe minimum price of the listings included in the campaign.

Occurrence: Optional

campaignCriterion.selectionRules.minPrice.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Optional

campaignCriterion.selectionRules.minPrice.valuestringThe monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaignNamestringA seller-defined name for the campaign. This value must be unique for the seller.

You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.

Max length: 80 characters

Occurrence: Required

endDatestringThe date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is blank (code>null), it indicates a campaign that has no end date. For display purposes, convert this time into the local time of the seller.

Occurrence: Optional

fundingStrategyFundingStrategyThis field specifies the funding model that defines how the Promoted Listing fee is calculated. The seller is assessed the fee if an item sells via a Promoted Listings action (such as buyer clicking on a Promoted Listings ad).

currently, the only funding model supported is COST_PER_SALE.

Occurrence: Required

fundingStrategy.bidPercentagestringThe user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

bidPercentage is a single precision value that is guided by the following rules:
  • These values are valid:
       1,    1.0,    4.1,
       5.0,    5.5, ...
  • These values are not valid:
       0.01,    10.75,    99.99,
       and so on.

If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Minimum value: 1.0
Maximum value: 100.0

Occurrence: Required

fundingStrategy.fundingModelFundingModelEnumIndicates the model that eBay uses to calculate the Promoted Listings fee. Currently, only COST_PER_SALE is supported.

Default: COST_PER_SALE

Occurrence: Required

marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace where the campaign is hosted. Note the X-EBAY-C-MARKETPLACE-Id header value is ignored for this purpose.

Occurrence: Required

startDatestringThe date and time the campaign starts, in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller.

On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign. Call getCampaign to check the status of the campaign.

Occurrence: Required

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationThe location response header contains the URL to the newly created ad campaign. The URL includes the eBay-assigned campaignId, which you can use to reference the campaign.

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
201Created
400Bad Request
409Business error
500Internal Server error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
35001API_MARKETINGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.
35002API_MARKETINGAPPLICATIONInternal error. Please wait a few minutes and try the call again.
35003API_MARKETINGREQUEST'campaignCriterion' is required for a criterion based campaign.
35004API_MARKETINGREQUESTOne of the selectionRule containers is empty. You must specify at least one rule in each selectionRule container. Note: 'categoryScope' is not a rule.
35005API_MARKETINGREQUEST'selectionRules' is required for criterion based campaigns.
35006API_MARKETINGREQUEST'fundingStrategy' is required for this call.
35007API_MARKETINGREQUESTThe 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}. Example of valid values: 4.1, 4.10, 5.5, 5.0, etc. Invalid values: 4.44, 8.11, etc.
35008API_MARKETINGREQUESTThe category ID {categoryId} is not valid.
35009API_MARKETINGREQUESTThe listing Condition ID {listingConditionId} is not valid. Refer to the API call documentation for a list of valid values.
35015API_MARKETINGREQUESTThe 'maxPrice' or 'minPrice' value is missing or invalid. The value cannot be less than or equal to zero.
35016API_MARKETINGREQUESTThe 'minPrice' {minPrice} cannot be greater than the 'maxPrice' {maxPrice}.
35017API_MARKETINGREQUEST'currency' is not valid or missing.
35019API_MARKETINGREQUESTCampaign name is required for this call.
35020API_MARKETINGREQUESTThe campaign name cannot be more than {maxCampaignNameLength} characters.
35021API_MARKETINGREQUESTA campaign with the name of {campaignName} already exists. Please provide a different name.
35022API_MARKETINGREQUESTThe brand name {brandName} is not valid.
35023API_MARKETINGREQUESTThe request contains invalid characters. {notAllowedCharacters} are not allowed.
35024API_MARKETINGREQUESTThe campaign start date {startDate} cannot be after the end date {endDate}.
35025API_MARKETINGREQUESTA campaign start date is required.
35026API_MARKETINGREQUESTA campaign start or end date {date} cannot be in the past.
35038API_MARKETINGREQUESTThe funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}.
35039API_MARKETINGREQUESTThe 'categoryScope' is required for criterion based campaigns using category based listing selection rules. Valid values are: {categoryScopeValues}
35041API_MARKETINGREQUESTThe 'marketplaceId' is required.
35042API_MARKETINGREQUESTThe criterion type is required for criterion based campaigns. Valid values are: {criterionTypeValues}.
35051API_MARKETINGBUSINESS'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}.
35052API_MARKETINGBUSINESSThe category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings.
35053API_MARKETINGBUSINESSMarketplaceId: {marketplaceId} and Currency: {currency} for the listing selection rule do not match.
35067API_MARKETINGBUSINESSThe seller must accept the Promoted Listing terms and conditions. For the requirements to use the Promoted Listing API, refer to the documentation.
35069API_MARKETINGBUSINESSNo more than {maxNumberOfSelectionRules} listing selection rules are allowed in a campaign.
35072API_MARKETINGBUSINESSThe number of listings that result from the rules exceeds the maximum number of listings allowed in a campaign, which is {maxSupportedNumber}. Refine the rules and submit the call again.
35074API_MARKETINGBUSINESSThere were no eligible listings found for the selection rules provided. Please check the rules and submit the call again.
35075API_MARKETINGBUSINESSThe category {categoryId} is not supported by the Promoted Listing service for single-quantity listings.
35077API_MARKETINGBUSINESSTo use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.
35078API_MARKETINGBUSINESSTo gain access to Promoted Listings, you must be in good standing with recent sales activity.

Warnings

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Create a Campaign for an Inventory Campaign

This sample creates a campaign named "Fall Sale," and sets the start date and bid percentage values, which will be used for all the ads in the campaign.

Input

The inputs for this sample are campaignName, startDate, fundingStrategy.bidPercentage, fundingStrategy.fundingModel and marketplaceId.
POST
https://api.ebay.com/sell/marketing/v1/ad_campaign

Output

A successful call returns the HTTP status code 201 Created.

In addition, the response includes a location response header that contains the URI to the newly created campaign. The returned URI also includes the ID to the newly created campaign.