POST/ad_campaign
This method can be used to create a Promoted Listings general, priority, or offsite campaign.
A Promoted Listings campaign is the structure in which you place the ads or ad group for the listings you wish to promote.
Note: Campaigns can only contain ads for a maximum of 50,000 items.
General strategy campaigns utilize a Cost Per Sale (CPS) funding model. Sellers can set the ad rate and bidding strategies that are right for their business through the adRateStrategy, biddingStrategy, bidPercentage fields. For more information on general strategy campaigns, see Promoted Listings general strategy campaign flow.
Priority strategy campaigns utilize a Cost per Click (CPC) funding model. Sellers can create a daily budget through the budget container and choose what channel that their ads appear on. In addition, priority strategy campaigns give sellers the ability to create ad groups and specify keywords to ensure their ads reach their intended audience. For more information on priority strategy campaigns, see Promoted listings priority strategy campaign flow.
Promoted Offsite campaigns give sellers the ability to create their own advertising campaign and promote their eBay listing in leading external search channels. For more information on Promoted Offsite campaigns, see Promoted Offsite.
Note: Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine their eligibility status for eBay advertising programs.
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
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 |
campaignTargetingType | CampaignTargetingTypeEnum | The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting campaign.
Occurrence: Conditional |
channels | array of ChannelEnum | The channel for the campaign. This value indicates whether the advertising campaign is an Onsite or Offsite.
OFF_SITE for a Promoted Offsite campaign. Occurrence: Conditional |
endDate | string | The date and time the campaign ends, in UTC format ( Occurrence: Optional |
fundingStrategy | FundingStrategy | This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value. Occurrence: Required |
fundingStrategy.adRateStrategy | AdRateStrategyEnum | This field is used to set the ad rate strategy for a Cost Per Sale (CPS) campaign. Occurrence: Conditional |
fundingStrategy.biddingStrategy | BiddingStrategyEnum | Indicates the bidding strategy for an onsite Cost Per Click (CPC) campaign that uses manual targeting.
Default value: FIXED 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. Note: This field has a minimum value of 2.0 and a maximum value of 100.0 . Occurrence: Conditional |
fundingStrategy.bidPreferences | array of BidPreference | This container indicates the bidding preferences of the campaign, such as the maximum CPC amount. Occurrence: Conditional |
fundingStrategy.bidPreferences.maxCpc | MaxCpc | The maximum amount for which the eBay suggested bid can be adjusted. This value represents the most a seller is willing to pay for each click on their ad. The adjusted bid will never exceed this amount. Occurrence: Conditional |
fundingStrategy.bidPreferences.maxCpc.amount | Amount | The allocated maximum CPC amount for a smart targeting campaign. Occurrence: Optional |
fundingStrategy.bidPreferences.maxCpc.amount.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
fundingStrategy.bidPreferences.maxCpc.amount.value | string | The monetary amount in the specified currency. 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. |
35094 | API_MARKETING | BUSINESS | Maximum number of campaigns allowed with the 'channels' value {channel} is exceeded. |
35095 | API_MARKETING | BUSINESS | 'marketplaceId' {marketplaceId} is not supported. Offsite Ads is supported only on these marketplaces: {supportedMarketplaces}. |
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. |
35124 | API_MARKETING | REQUEST | The 'maxCpc' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}. |
35125 | API_MARKETING | REQUEST | The 'bidPreferences' list currently supports only one element. Please remove additional elements and try again. |
35127 | API_MARKETING | BUSINESS | 'maxCPC' is only supported for CPC funding model campaigns with on-site channels and smart targeting type. |
35128 | API_MARKETING | BUSINESS | 'campaignTargetingType' is only supported for CPC funding model campaigns with on-site channels. |
35132 | API_MARKETING | BUSINESS | The 'biddingStrategy' field is not supported for CPS funding model. |
35134 | API_MARKETING | REQUEST | A 'biddingStrategy' cannot be supplied for smart targeting campaigns. Please either remove 'biddingStrategy' from the request to create a smart targeting campaign or supply another value for 'campaignTargetingType'. |
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}. |
36161 | API_MARKETING | REQUEST | Smart targeting campaigns require a `bidPreferences.maxCpc` value. |
36162 | API_MARKETING | REQUEST | The 'maxCpc' currency should be the same as the daily budget. |
36163 | API_MARKETING | REQUEST | The 'maxCpc' value {maxCpcValue} is below minimum value {maxCpcMinimumValue}. |
36164 | API_MARKETING | REQUEST | The 'maxCpc' value {maxCpcValue} is above maximum value {maxCpcMaximumValue}. |
36165 | API_MARKETING | REQUEST | The 'maxCpc' value {maxCpcValue} is more than maximum daily budget {maxDailyBudget}. |
36166 | API_MARKETING | REQUEST | The 'maxCpc' value {maxCpcValue} is invalid. Refer to the API call documentation for more information. |
36406 | API_MARKETING | REQUEST | The 'channels' value {channel} can only be used with the {funding_model} fundingModel. |
36407 | API_MARKETING | REQUEST | The 'channels' value is invalid. |
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. |
36410 | API_MARKETING | BUSINESS | This campaign has been created with the suggested budget. |
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 general strategy campaign
This sample creates a Promoted Listings general strategy 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
{"campaignName": "Fall Sale","startDate": "2016-09-07T21:43:00Z","fundingStrategy": {"bidPercentage": "10.0","fundingModel": "COST_PER_SALE"},"marketplaceId": "EBAY_US"}
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.
Sample 2: Create a manual targeting priority strategy campaign
This sample creates a manual targeting Promoted Listings priority strategy campaign that incorporates a dynamic bidding strategy.
Input
This sample creates a manual targeting campaign that incorporates a dynamic bidding strategy. When a campaign uses dynamic bidding sellers can manually update keywords for the campaign, but they are not able to manually adjust the associated bid values.
In order to manually adjust bid values, sellers must call updateBiddingStrategy to set biddingStrategy to FIXED
to use a fixed bidding strategy.
POSThttps://api.ebay.com/sell/marketing/v1/ad_campaign
{"campaignName": "Fall Sale","startDate": "2023-10-05T13:42:18.094Z","endDate": "2023-10-07T13:42:18.094Z","fundingStrategy": {"fundingModel": "COST_PER_CLICK","biddingStrategy": "DYNAMIC"},"marketplaceId": "EBAY_US","budget": {"daily": {"amount": {"value": 10,"currency": "USD"}}}}
Output
A successful call returns the HTTP status code 201 Created.
In addition, the response includes a location response header that provides the URI to the newly created campaign. This method has no response payload.
Sample 3: Create a smart targeting priority strategy campaign
This sample creates a smart targeting Promoted Listings priority strategy campaign and specifies the maximum CPC the seller is willing to pay.
Input
This sample creates a smart targeting campaign with a maximum cost per click of $0.50.
To create a smart targeting campaign, the campaignTargetingType must be set to SMART
and the MaxCpc (the maximum value the the seller is willing to pay per click on their ad) must be specified in the request.
POSThttps://api.ebay.com/sell/marketing/v1/ad_campaign
{"campaignName": "Fall Sale","startDate": "2023-10-05T13:42:18.094Z","endDate": "2023-10-07T13:42:18.094Z","fundingStrategy": {"fundingModel": "COST_PER_CLICK","bidPreferences": [{"maxCpc": {"amount": {"value": 0.5,"currency": "USD"}}}]},"campaignTargetingType": "SMART","marketplaceId": "EBAY-US","budget": {"daily": {"amount": {"value": 10,"currency": "USD"}}}}
Output
A successful call returns the HTTP status code 201 Created.
In addition, the response includes a location response header that provides the URI to the newly created campaign. This method has no response payload.
Sample 4: Create a Promoted Offsite campaign
This sample creates an Promoted Offsite campaign and sets the start date, funding strategy, and budget for the campaign.
Input
The inputs for this sample are campaignName, startDate, fundingStrategy, channels, budget and marketplaceId.
In this sample, the seller has created an offsite campaign with a daily budget of 5 USD.
POSThttps://api.ebay.com/sell/marketing/v1/ad_campaign
{"campaignName": "Offsite ads Campaign","startDate": "2023-07-07T21:43:00Z","fundingStrategy": {"fundingModel": "COST_PER_CLICK"},"channels": ["OFF_SITE"],"budget": {"daily": {"amount": {"currency": "USD","value": "5"}}},"marketplaceId": "EBAY_US"}
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 Promoted Offsite campaign. This method has no response payload.