Skip to main content

POST/ad_campaign/setup_quick_campaign

This method allows the seller to expedite the creation of a Promoted Listings Advanced (PLA) campaign.

Sellers only need to provide basic campaign information, such as the user-defined campaign name, the start date (and optionally the end date) of the campaign, the daily budget amount of the campaign, and the eBay marketplace where the campaign will be hosted. The seller must also identify the items they want to place in the campaign by adding the listing id of each item in the listingIds array of the request.

Using the provided listingIds, eBay creates ad groups for the campaign and organizes the listings into the appropriate ad group. eBay then adds keywords to each ad group and assigns each keyword a suggested bid.

By default, campaigns created using setupQuickCampaign utilize a FIXED keyword bidding strategy which means that a seller manually assigns and adjusts keyword bids for their CPC campaign.

Alternatively, once the campaign has been created, sellers may opt to utilize a DYNAMIC bidding strategy which means that eBay will manage a campaign's keyword bids and automatically update them daily to the suggested bid.

For additional information about FIXED and DYNAMIC bidding strategies, refer to updateBiddingStrategy.

Campaigns created using this method will be in DRAFT status upon creation.

The location response header returned contains the getCampaign URI to retrieve the newly created campaign that is in draft status. Sellers should make this call to review and approve the campaign before they use the launchCampaign method to start the campaign.

Note: Promoted Listing Standard (PLS) campaigns are not supported.

Input

Resource URI

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

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.

HeaderTypeDescription
Content-TypestringThis 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 clipboard

Request fields

Input container/fieldTypeDescription
budgetCampaignBudgetRequest

The allocated daily budget for a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.

Occurrence: Required

budget.dailyBudgetRequest

The daily budget limit for a CPC Promoted Listings campaign.

When running an Offsite Ads campaign, eBay may spend more or less than the seller's daily budget to capitalize on interested buyers, but will not exceed 2x the daily budget. The average over the course of the campaign will not exceed the provided daily budget. This value is used to calculate a total monthly budget by multiplying 30.4 by the provided daily budget. Over the course of the campaign, eBay will not charge more than this total budget per month.

If a campaign ends prematurely, however, the seller may be charged up to 2x their daily budget on a daily basis, as the campaign may have not had the chance to average the budget out over time.

Occurrence: Required

budget.daily.amountAmount

The allocated budget amount for a CPC Promoted Listings campaign. Both the currency and value must be specified.

Occurrence: Required

budget.daily.amount.currencyCurrencyCodeEnum

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

Occurrence: Conditional

budget.daily.amount.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaignNamestring

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

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

Max Length: 80 characters

Occurrence: Required

endDatestring

The date and time the campaign is scheduled to end, in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).

If this field is omitted, the campaign will have no defined end date, and will not end until the seller ends the campaign using the endCampaign method, or if they update the campaign to include an end date using the updateCampaignIdentification method. This date must be further in the future than the startDate.

Occurrence: Optional

listingIdsarray of string

This array includes the listing Ids of the items that are to be associated with the PLA campaign. eBay will create ad groups and keywords for these listings and add them to the campaign.

Each value must be delimited by a comma. A maximum of 1000 listing Ids can be added to a campaign created using the setupQuickCampaign method.

Occurrence: Required

marketplaceIdMarketplaceIdEnum

The Id of the marketplace where the campaign is hosted. See the MarkeplaceIdEnum type for more details.

Occurrence: Required

startDatestring

The date and time the campaign is scheduled to start, in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).

On the specified date, 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 once 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.

Note: If the startDate has passed by the time the seller launches a campaign, the campaign will be updated to RUNNING status. If the seller launches a campaign before the startDate, the campaign will be updated to SCHEDULED status and will change to RUNNING status at the time of the specified startDate.

Occurrence: Required

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationThe location response header contains the getCampaign URI to the newly created quick setup 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.

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.
35006API_MARKETINGREQUEST'fundingStrategy' is required for this call.
35014API_MARKETINGREQUESTThe listing Id is required for this call.
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.
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.
35037API_MARKETINGREQUESTThe listing associated with listing Id {listingId} has ended.
35038API_MARKETINGREQUESTThe funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}.
35041API_MARKETINGREQUESTThe 'marketplaceId' is required.
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.
35054API_MARKETINGBUSINESSThe listing Id {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace.
35057API_MARKETINGBUSINESSThe listing Id {listingId} does not belong to the seller making this call.
35058API_MARKETINGBUSINESSThe listing Id {listingId} is not a fixed price item. This is a requirement for a promoted listing.
36152API_MARKETINGBUSINESSThe 'bidPercentage' is not supported for CPC funding model.
36153API_MARKETINGBUSINESSThe daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}.
36154API_MARKETINGBUSINESSThe daily budget below minimum allowed {minAllowed}.
36155API_MARKETINGBUSINESSThe daily budget above maximum allowed {maxAllowed}.
36157API_MARKETINGBUSINESSThe daily budget is required for campaigns with CPC funding model.
36158API_MARKETINGBUSINESSThe daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places.
36159API_MARKETINGBUSINESS'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}.
36160API_MARKETINGREQUESTThis functionality is only supported for CPC funding model.
36363API_MARKETINGBUSINESSQuick setup is unavailable for the selected listings. Please check the listings and submit the call again.

Warnings

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

CodeDomainCategoryMeaning
36362API_MARKETINGBUSINESSQuick setup is unavailable for the {count} of the selected listings.
36365API_MARKETINGBUSINESSThe category is not supported by the Promoted Listing service for multi-quantity listings.
36366API_MARKETINGBUSINESSThe listing id was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace.
36367API_MARKETINGBUSINESSThe listing id does not belong to the seller making this call.
36368API_MARKETINGBUSINESSThe listing id is not a fixed price item. This is a requirement for a promoted listing.
36369API_MARKETINGREQUESTThe listing id is invalid or has ended.

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 Quick Setup PLA Campaign

This sample creates a quick setup PLA campaign named "Spring Sale." This campaign uses the CPC funding model and has a specified start and end date. A single listing is associated with this campaign.

Input

The inputs for this sample are campaignName, startDate, endDate, marketplaceId, budget, and listingIds.

POSThttps://api.ebay.com/sell/marketing/v1/ad_campaign/setup_quick_campaign

Output

If the call is successful, HTTP status code 201 Created is returned and the campaign is created in DRAFT status. Sellers can then use the launchCampaign method to start, or schedule to start, the campaign.

In addition, the response contains a location response header that contains the getCampaign URI to the newly created campaign. This method has no response payload.