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 and COST_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.

Servers

https://api.ebay.com{basePath}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`budget`	Object	No	A container for the details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.
`budget.daily`	Object	No	A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model. Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model.
`budget.daily.amount`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`budget.daily.amount.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`budget.daily.amount.currency`	String	No	The 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. For implementation help, refer to eBay API documentation
`endDate`	String	No	The date and time the campaign ends, in UTC format (`yyyy-MM-ddThh:mm:ssZ`). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date.
`campaignCriterion`	Object	No	This type defines the fields for specifying the criterion (selection rule) settings of an ad 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 newly created campaign.
`campaignCriterion.autoSelectFutureInventory`	Boolean	No	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. If set to `true`, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory. Default: `false`
`campaignCriterion.selectionRules[]`	Array	No	This container shows all of the rules/inclusion filters used to add listings to the campaign.
`campaignCriterion.selectionRules[].maxPrice`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`campaignCriterion.selectionRules[].maxPrice.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`campaignCriterion.selectionRules[].maxPrice.currency`	String	No	The 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. For implementation help, refer to eBay API documentation
`campaignCriterion.selectionRules[].categoryIds[]`	Array	No	A list of category IDs associated with the listings to be included in the campaign. Ads 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: See Category Changes for the latest list of category IDs. Retrieve a list of category IDs using the Taxonomy API. 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: Go to Seller Hub > Marketing. Click Manage store categories. A list of your store categories displays. 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.
`campaignCriterion.selectionRules[].categoryScope`	String	No	The enumeration values returned in this field indicate if the category IDs in the corresponding categoryIds array are identifiers for eBay categories or for a seller's eBay store categories. This field is always returned if one or more category IDs are used as a filter. For implementation help, refer to eBay API documentation
`campaignCriterion.selectionRules[].listingConditionIds[]`	Array	No	A comma-separated list of unique identifiers for the conditions of listings to be included in the campaign. Up to four IDs can be specified. This array is only returned if one or more item condition values are used as a filter. Note: Multiple listing condition IDs are mapped to the four valid values listed below. Refer to Promoted Listings Standard campaign flow for more details. Valid Values: `1000` = New `2000` = Certified Refurbished `2500` = Seller Refurbished `3000` = Used
`campaignCriterion.selectionRules[].minPrice`	Object	No	A complex type that describes the value of a monetary amount as represented by a global currency.
`campaignCriterion.selectionRules[].minPrice.value`	String	No	The monetary amount in the specified currency. Required in the amount type.
`campaignCriterion.selectionRules[].minPrice.currency`	String	No	The 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. For implementation help, refer to eBay API documentation
`campaignCriterion.selectionRules[].brands[]`	Array	No	An array of product brands used as an inclusion filter. A product's brand is defined in a listing's item specifics. This array will be returned if one or more product brands were used as a filter.
`campaignCriterion.criterionType`	String	No	This 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. Do not include this field if you manage your listings with Trading API/legacy model. For implementation help, refer to eBay API documentation
`campaignName`	String	No	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 characters
`startDate`	String	No	The 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.
`fundingStrategy`	Object	No	This type defines how the Promoted Listings fee is calculated for a Promoted Listings ad campaign.
`fundingStrategy.fundingModel`	String	No	Indicates the model that eBay uses to calculate the Promoted Listings fee. For a description of the funding model types, refer to FundingModelTypeEnum. For implementation help, refer to eBay API documentation
`fundingStrategy.bidPercentage`	String	No	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. 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. The bidPercentage is a single precision value that is guided by the following rules: These values are valid: `4.1`, `5.0`, `5.5`, ... These values are not valid: `0.01`, `10.75`, `99.99`, and so on. This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages. 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. It is not used for campaigns that use the Cost Per Click (CPC) funding model. Minimum value: 2.0 Maximum value: 100.0
`fundingStrategy.adRateStrategy`	String	No	The ad rate strategy that shall be applied to the campaign. For implementation help, refer to eBay API documentation
`fundingStrategy.dynamicAdRatePreferences[]`	Array	No	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. Note: Dynamic adjustment is only applicable when the adRateStrategy is set to `DYNAMIC`. Default: `FIXED`
`fundingStrategy.dynamicAdRatePreferences[].adRateCapPercent`	String	No	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.
`fundingStrategy.dynamicAdRatePreferences[].adRateAdjustmentPercent`	String	No	The percentage above or below (-) the eBay suggested ad rate that a seller is willing to pay. This specifies the maximum and minimum values to which an ad rate can be dynamically adjusted.
`marketplaceId`	String	No	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. For implementation help, refer to eBay API documentation

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.