POST/ad_campaign
This method creates a Promoted Listings ad campaign.
A Promoted Listings campaign is the structure into which you place the ads or ad group 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. 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. - 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.
- Add an ad group to an existing campaign by calling createAdGroup.
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 supported funding models are
COST_PER_SALE
andCOST_PER_CLICK
. 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 Promoted Listings campaign creation.
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. See Promoted Listings restrictions for details about campaign limitations and restrictions.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com
root URI with api.sandbox.ebay.com
URI parameters
This method has no URI parameters.
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
Header | Type | Description |
---|---|---|
Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required |
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.
Request payload
Copy complete valid JSON to clipboardRequest fields
Input container/field | Type | Description |
---|---|---|
budget | CampaignBudgetRequest | The allocated daily budget for the Cost Per Click (CPC) Promoted Listings campaign. Occurrence: Conditional |
budget.daily | BudgetRequest | The daily budget limit for a CPC Promoted Listings campaign. Occurrence: Required |
budget.daily.amount | Amount | The allocated budget amount for a CPC Promoted Listings campaign. Both the currency and value must be specified. Occurrence: Required |
budget.daily.amount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
budget.daily.amount.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
campaignCriterion | CampaignCriterion | This container is used if the seller wishes to create one or more rules for a rules-based campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign to be created. Occurrence: Optional |
campaignCriterion.autoSelectFutureInventory | boolean | A field used to indicate whether listings shall be automatically added to, or removed from, a Promoted Listings campaign based on the rules that have been configured for the campaign. Occurrence: Optional |
campaignCriterion.criterionType | CriterionTypeEnum | This enum defines the criterion (selection rule) types. Currently, the only criterion type supported is Occurrence: Conditional |
campaignCriterion.selectionRules | array of SelectionRule | This container shows all of the rules/inclusion filters used to add listings to the campaign. For information on using the contained fields, see Promoted Listing campaigns. Occurrence: Conditional |
campaignCriterion.selectionRules.brands | array of string | An array of product brands. For more details, see Using the selectionRules container. Occurrence: Optional |
campaignCriterion.selectionRules.categoryIds | array of string | This field contains an array of the associated category ID(s). Occurrence: Conditional |
campaignCriterion.selectionRules.categoryScope | CategoryScopeEnum | This enumerated value indicates if the category ID for the item is an identifier for eBay categories or for a seller's eBay store categories. Occurrence: Conditional |
campaignCriterion.selectionRules.listingConditionIds | array of string | A comma-separated list of unique identifiers for the conditions of listings to be included Occurrence: Optional |
campaignCriterion.selectionRules.maxPrice | Amount | This container sets the maximum price threshold. For more details, see Using the selectionRules container. Occurrence: Optional |
campaignCriterion.selectionRules.maxPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
campaignCriterion.selectionRules.maxPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
campaignCriterion.selectionRules.minPrice | Amount | This container sets the minimum price threshold. For more details, see Using the selectionRules container. Occurrence: Optional |
campaignCriterion.selectionRules.minPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
campaignCriterion.selectionRules.minPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
campaignName | string | A 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 charactersOccurrence: Required |
endDate | string | The date and time the campaign ends, in UTC format ( Occurrence: Optional |
fundingStrategy | FundingStrategy | This container is used to set the funding model and default bid percentage for a Cost Per Sale (CPS) campaign. Occurrence: Required |
fundingStrategy.adRateStrategy | AdRateStrategyEnum | The ad rate strategy that shall be applied to the campaign. Occurrence: Optional |
fundingStrategy.bidPercentage | string | The 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.
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign. Note:This field is only relevant for campaigns that use the CPS funding model and a fixed ad rate. It is not used for campaigns that use the Cost Per Click (CPC) funding model and should not be provided when the selected adRateStrategy for the campaign is dynamic. Minimum value: 2.0 Maximum value: 100.0 Occurrence: Conditional |
fundingStrategy.dynamicAdRatePreferences | array of DynamicAdRatePreference | A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage. Occurrence: Optional |
fundingStrategy.dynamicAdRatePreferences.adRateAdjustmentPercent | string | The percentage above or below (-) the eBay suggested ad rate that a seller is willing to pay. Occurrence: Optional |
fundingStrategy.dynamicAdRatePreferences.adRateCapPercent | string | The maximum value (specified as a percentage) to which the eBay suggested ad rate can be adjusted. The adjusted ad rate will never exceed this percentage. Occurrence: Optional |
fundingStrategy.fundingModel | FundingModelEnum | Indicates the model that eBay uses to calculate the Promoted Listings fee. For a description of the funding model types, refer to FundingModelTypeEnum. Occurrence: Required |
marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace where the campaign is hosted. See the MarketplaceIdEnum type to get the appropriate enumeration value for the listing marketplace. Occurrence: Required |
startDate | string | The date and time the campaign starts, in UTC format ( 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.
Header | Meaning |
---|---|
Location | The location response header contains the getCampaign URI to the newly created campaign. The URL includes the eBay-assigned campaignId , which you can use to reference the campaign. |
Response payload
This call has no payload.
Response fields
This call has no field definitions.
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.
Status | Meaning |
---|---|
201 | Created |
400 | Bad Request |
409 | Business error |
500 | Internal Server error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
35001 | API_MARKETING | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance. |
35002 | API_MARKETING | APPLICATION | Internal error. Please wait a few minutes and try the call again. |
35003 | API_MARKETING | REQUEST | 'campaignCriterion' is required for a criterion based campaign. |
35004 | API_MARKETING | REQUEST | One of the selectionRule containers is empty. You must specify at least one rule in each selectionRule container. Note: 'categoryScope' is not a rule. |
35005 | API_MARKETING | REQUEST | 'selectionRules' is required for criterion based campaigns. |
35006 | API_MARKETING | REQUEST | 'fundingStrategy' is required for this call. |
35007 | API_MARKETING | REQUEST | The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}. |
35008 | API_MARKETING | REQUEST | The category ID {categoryId} is not valid. |
35009 | API_MARKETING | REQUEST | The listing Condition ID {listingConditionId} is not valid. Refer to the API call documentation for a list of valid values. |
35015 | API_MARKETING | REQUEST | The 'maxPrice' or 'minPrice' value is missing or invalid. The value cannot be less than or equal to zero. |
35016 | API_MARKETING | REQUEST | The 'minPrice' {minPrice} cannot be greater than the 'maxPrice' {maxPrice}. |
35017 | API_MARKETING | REQUEST | 'currency' is not valid or missing. |
35019 | API_MARKETING | REQUEST | Campaign name is required for this call. |
35020 | API_MARKETING | REQUEST | The campaign name cannot be more than {maxCampaignNameLength} characters. |
35021 | API_MARKETING | REQUEST | A campaign with the name of {campaignName} already exists. Please provide a different name. |
35022 | API_MARKETING | REQUEST | The brand name {brandName} is not valid. |
35023 | API_MARKETING | REQUEST | The request contains invalid characters. {notAllowedCharacters} are not allowed. |
35024 | API_MARKETING | REQUEST | The campaign start date {startDate} cannot be after the end date {endDate}. |
35025 | API_MARKETING | REQUEST | A campaign start date is required. |
35026 | API_MARKETING | REQUEST | A campaign start or end date {date} cannot be in the past. |
35038 | API_MARKETING | REQUEST | The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}. |
35039 | API_MARKETING | REQUEST | The 'categoryScope' is required for criterion based campaigns using category based listing selection rules. Valid values are: {categoryScopeValues} |
35041 | API_MARKETING | REQUEST | The 'marketplaceId' is required. |
35042 | API_MARKETING | REQUEST | The criterion type is required for criterion based campaigns. Valid values are: {criterionTypeValues}. |
35051 | API_MARKETING | BUSINESS | 'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}. |
35052 | API_MARKETING | BUSINESS | The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings. |
35053 | API_MARKETING | BUSINESS | MarketplaceId: {marketplaceId} and Currency: {currency} for the listing selection rule do not match. |
35067 | API_MARKETING | BUSINESS | The seller must accept the Promoted Listing terms and conditions. For the requirements to use the Promoted Listing API, refer to the documentation. |
35069 | API_MARKETING | BUSINESS | No more than {maxNumberOfSelectionRules} listing selection rules are allowed in a campaign. |
35072 | API_MARKETING | BUSINESS | The 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. |
35074 | API_MARKETING | BUSINESS | There were no eligible listings found for the selection rules provided. Please check the rules and submit the call again. |
35075 | API_MARKETING | BUSINESS | The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings. |
35077 | API_MARKETING | BUSINESS | To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity. |
35078 | API_MARKETING | BUSINESS | To gain access to Promoted Listings, you must be in good standing with recent sales activity. |
35089 | API_MARKETING | BUSINESS | We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. |
35104 | API_MARKETING | BUSINESS | 'categoryScope' STORE can not be found. Please define the store categories first or use 'categoryScope' MARKETPLACE to select categories. |
35106 | API_MARKETING | BUSINESS | 'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'. |
35107 | API_MARKETING | BUSINESS | 'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'. |
35108 | API_MARKETING | BUSINESS | The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%. |
35109 | API_MARKETING | BUSINESS | The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%. |
35110 | API_MARKETING | BUSINESS | The 'adRateStrategy' is not supported for CPC funding model. |
35111 | API_MARKETING | BUSINESS | The 'dynamicAdRatePreferences' is not supported for CPC funding model. |
35114 | API_MARKETING | BUSINESS | The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again. |
36101 | API_MARKETING | REQUEST | The daily budget value format is a maximum of two decimal points. |
36151 | API_MARKETING | BUSINESS | 'campaignCriterion' {campaignCriterion} is not supported for CPC funding model. |
36152 | API_MARKETING | BUSINESS | The 'bidPercentage' is not supported for CPC funding model. |
36153 | API_MARKETING | BUSINESS | The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}. |
36154 | API_MARKETING | BUSINESS | The daily budget below minimum allowed {minAllowed}. |
36155 | API_MARKETING | BUSINESS | The daily budget above maximum allowed {maxAllowed}. |
36156 | API_MARKETING | BUSINESS | campaignBudget is not supported for CPS funding model. |
36157 | API_MARKETING | BUSINESS | The daily budget is required for campaigns with CPC funding model. |
36158 | API_MARKETING | BUSINESS | The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places. |
36159 | API_MARKETING | BUSINESS | 'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
35103 | API_MARKETING | BUSINESS | This campaign has reached maximum capacity of {maxSupportedNumber} listings. To continue promoting listings, create a new campaign. |
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.
POSThttps://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. This method has no response payload.