Skip to main content

GET/ad_campaign

This method retrieves the details for all of the seller's defined campaigns. Request parameters can be used to retrieve a specific campaign, such as the campaign's name, the start and end date, the channel, the status, and the funding model (i.e., Cost Per Sale (CPS) or Cost Per Click (CPC)).

You can filter the result set by a campaign name, end date range, start date range, campaign channel, or campaign status. You can also paginate the records returned from the result set using the limit query parameter, and control which records to return using the offset parameter.

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

ParameterTypeDescription
campaign_statusstringThis query parameter specifies the status of the campaign(s) being retrieved.

Note: The results might not include all the campaigns with this status if other filters exclude them.
Valid values: See CampaignStatusEnum

Maximum: 1 status

Occurrence: Optional

start_date_rangestringThis query parameter specifies the range of a campaign's start date in which to filter the results. The results are filtered to include only campaigns with a start date that is equal to this date or is within specified range.

Valid format (UTC):
  • yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (starts within this range)
  • yyyy-MM-ddThh:mm:ssZ (campaign starts on or after this date)
  • ..yyyy-MM-ddThh:mm:ssZ (campaign starts on or before this date)
  • 2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign starts on September 08, 2016)

Note: The results might not include all the campaigns with this start date if other filters exclude them.

Occurrence: Optional

end_date_rangestringThis query parameter specifies the range of a campaign's end date. The results are filtered to include only campaigns with an end date that is within specified range.

Valid format (UTC):
  • yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (campaign ends within this range)
  • yyyy-MM-ddThh:mm:ssZ.. (campaign ends on or after this date)
  • ..yyyy-MM-ddThh:mm:ssZ (campaign ends on or before this date)
  • 2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign ends on September 08, 2016)

Note:The results might not include all the campaigns ending on this date if other filters exclude them.

Occurrence: Optional

campaign_namestringThis query parameter specifies the name of the campaign being retrieved. The results are filtered to include only the campaign by the specified name.

Use the getCampaigns method to retrieve a list of a seller's campaign names.

Note: The results might be null if other filters exclude the campaign with this name.

Maximum: 1 campaign name

Occurrence: Optional

funding_strategystringThis query parameter specifies the funding strategy for the campaign(s) being retrieved.

The results will be filtered to only include campaigns with the specified funding model. If not specified, all campaigns matching the other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.

Valid Values: See FundingModelEnum

Occurrence: Optional

channelsstringThis query parameter specifies the channel for the the campaign(s) being retrieved.

The results will be filtered to only include campaigns with the specified channel. If not specified, all campaigns matching other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.

Valid Values: See ChannelEnum

Occurrence: Optional

limitstring

This query parameter specifies the maximum number of campaigns to return on a page in the paginated response.

Default: 10

Maximum: 500

Occurrence: Optional

offsetstringThis query parameter specifies the number of campaigns to skip in the result set before returning the first report in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.

Default: 0

Occurrence: Optional

HTTP request headers

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

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

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.readonly

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

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* CampaignPagedCollectionResponse */
"campaigns" : [
{ /* Campaign */ }
],
"href" : "string",
"limit" : "integer",
"next" : "string",
"prev" : "string",
}

Response fields

Output container/fieldTypeDescription
campaignsarray of Campaign

This array contains all of the seller's campaign that match the request criteria.

Occurrence: Always

campaigns.alertsarray of Alert

This array contains alert messages for the campaign.

Occurrence: Conditional

campaigns.alerts.alertTypeAlertTypeEnum

The type of alert message. For example, an invalid bid percentage.

Occurrence: Conditional

campaigns.alerts.detailsarray of AlertDetails

A description of the alert including dimensions and aspects.

Occurrence: Conditional

campaigns.alerts.details.dimensionAlertDimension

The dimension information of the alert including keys and values.

Occurrence: Conditional

campaigns.alerts.details.dimension.keyDimensionKeyEnum

The key field of the applied dimension. For example, the marketplace Id.

Occurrence: Conditional

campaigns.alerts.details.dimension.valuestring

The value field of the applied dimension. For example, if the key is a MARKETPLACE_ID, the value would be from MarketplaceIdEnum.

Occurrence: Conditional

campaigns.alerts.details.aspectAspect

The aspect information of the alert including keys and values.

Occurrence: Conditional

campaigns.alerts.details.aspect.keyAspectKeyEnum

The type of the aspect. For example, MINIMUM_REQUIRED.

Occurrence: Conditional

campaigns.alerts.details.aspect.valuestring

The value of the aspect. For example, if the aspect is a percentage, a value of '2.0' would equal 2%.

Occurrence: Conditional

campaigns.budgetCampaignBudget

The allocated budget for the Cost Per Click (CPC) Promoted Listings campaign.Note: This field will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model.

Occurrence: Conditional

campaigns.budget.dailyBudget

The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign.

Required if the campaign's funding model is CPC.

This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.

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.

Valid Values:

  • 50.00
  • 100.00

Occurrence: Conditional

campaigns.budget.daily.amountAmount

The allocated budget amount for a CPC Promoted Listings campaign.

Occurrence: Conditional

campaigns.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.

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

Occurrence: Conditional

campaigns.budget.daily.amount.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaigns.budget.daily.budgetStatusBudgetStatusEnum

The budget status for a CPC Promoted Listings campaign.

Occurrence: Conditional

campaigns.campaignCriterionCampaignCriterion

The selection rules (criterion) used to select the listings for a 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.Note: This container is only returned for rules-based campaigns using the Cost Per Sale (CPS) funding model.

Occurrence: Conditional

campaigns.campaignCriterion.autoSelectFutureInventoryboolean

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

Occurrence: Conditional

campaigns.campaignCriterion.criterionTypeCriterionTypeEnum

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.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRulesarray 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

campaigns.campaignCriterion.selectionRules.brandsarray of string

An array of product brands. For more details, see Using the selectionRules container.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.categoryIdsarray of string

This field contains an array of the associated category ID(s).

For Item promotions, a single-item array containing the category ID associated with the promotion. Required when used in an Item promotion and either specifying a selectionRules container or when inventoryCriterionType is set to INVENTORY_BY_RULE.

For Promoted Listing campaigns, an array of category ID(s) associated with the campaign.

For information on how to get category IDs, see eBay Marketplace category IDs and Seller store category IDs

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.categoryScopeCategoryScopeEnum

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.

For Promoted Listing campaigns, this field includes the type of the category ID for the item(s) to be included in the campaign.

For Item promotions, this field identifies the scope for the corresponding array as eBay categories or for a seller's eBay store categories. Required when used in an Item promotion and inventoryCriterionType is set to INVENTORY_BY_RULE.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.listingConditionIdsarray of string

A comma-separated list of unique identifiers for the conditions of listings to be included

For Promoted Listing campaigns, refer to Add items to the PLS campaign. Up to four IDs can be specified.

For Item promotions, refer to Item condition ID and name values.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.maxPriceAmount

This container sets the maximum price threshold. For more details, see Using the selectionRules container.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.maxPrice.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.

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

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.maxPrice.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.minPriceAmount

This container sets the minimum price threshold. For more details, see Using the selectionRules container.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.minPrice.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.

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

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.minPrice.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaigns.campaignIdstring

A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created.

Occurrence: Always

campaigns.campaignNamestring

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

Occurrence: Always

campaigns.campaignStatusCampaignStatusEnum

Indicates the status of the campaign, such as RUNNING, PAUSED, and ENDED.

Occurrence: Always

campaigns.channelsarray of ChannelEnum

The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign.

Valid Values:

  • ON_SITE
  • OFF_SITE

Occurrence: Conditional

campaigns.endDatestring

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.

Occurrence: Always

campaigns.fundingStrategyFundingStrategy

This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.

Currently, the supported funding models are COST_PER_SALE (CPS) and COST_PER_CLICK (CPC). For onsite ads, the CPC model supports two bidding strategies: FIXED and DYNAMIC.

Occurrence: Always

campaigns.fundingStrategy.adRateStrategyAdRateStrategyEnum

This field is used to set the ad rate strategy for a Cost Per Sale (CPS) campaign.

The default value for this field is FIXED. If this field is omitted, the default value will be used.

Note: This field is not applicable for Cost Per Click (CPC) or Offsite Ads campaigns.

Occurrence: Conditional

campaigns.fundingStrategy.biddingStrategyBiddingStrategyEnum

Indicates the bidding strategy for an onsite Cost Per Click (CPC) campaign.

Note: This field is applicable only to onsite Cost Per Click (CPC) campaigns.
Valid values are:

  • FIXED

    When using a fixed bidding strategy, sellers manually assign and adjust keyword bids for the CPC campaign.
  • DYNAMIC

    When using a dynamic bidding strategy, eBay manages the campaign's keyword bids and automatically updates them daily to the suggested bid.

    Note: For a CPC campaign using dynamic bidding, sellers can continue to manually add keywords for the campaign, but they are no longer able to manually adjust their associated bid values. In order to manually adjust bid values, sellers must use the FIXED bidding strategy.


Default value: FIXED

Occurrence: Conditional

campaigns.fundingStrategy.bidPercentagestring

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 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

campaigns.fundingStrategy.dynamicAdRatePreferencesarray 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.

Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC This field is not applicable for Offsite Ads campaigns.
Default: FIXED

Occurrence: Conditional

campaigns.fundingStrategy.dynamicAdRatePreferences.adRateAdjustmentPercentstring

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.

Occurrence: Conditional

campaigns.fundingStrategy.dynamicAdRatePreferences.adRateCapPercentstring

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: Conditional

campaigns.fundingStrategy.fundingModelFundingModelEnum

Indicates the model that eBay uses to calculate the Promoted Listings fee.

For a description of the funding model types, refer to FundingModelTypeEnum.

Occurrence: Always

campaigns.marketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace where the campaign is hosted.

Occurrence: Always

campaigns.startDatestring

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.

Occurrence: Always

hrefstring

The URI of the current page of results from the result set.

Occurrence: Always

limitinteger

The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.

Occurrence: Always

nextstring

The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

offsetinteger

The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

Occurrence: Always

prevstring

The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.

Max length: 2048

Occurrence: Conditional

totalinteger

The total number of campaigns retrieved in the result set.

If no campaigns are found, this field is returned with a value of 0.

Occurrence: Always

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
200Success
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.
35020API_MARKETINGREQUESTThe campaign name cannot be more than {maxCampaignNameLength} characters.
35023API_MARKETINGREQUESTThe request contains invalid characters. {notAllowedCharacters} are not allowed.
35027API_MARKETINGREQUESTThe date range {dateRange} is not valid. Ensure the beginning of the range is before the end of the range.
35028API_MARKETINGREQUESTThe format of the date range {dateRange} is invalid. The format for a date range is yyyy-MM-ddThh:mm:ss.sssZ..yyyy-MM-ddThh:mm:ss.sssZ or yyyy-MM-ddThh:mm:ss.sssZ.. or ..yyyy-MM-ddThh:mm:ss.sssZ.
35029API_MARKETINGREQUESTThe 'limit' has to be greater than zero and less than {maxLimitValue}.
35030API_MARKETINGREQUESTThe 'offset' cannot be less than zero.
35043API_MARKETINGREQUESTThe campaign status of {campaignStatus} is either invalid or not supported for this operation.
35077API_MARKETINGBUSINESSTo use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.
35079API_MARKETINGREQUESTFunding strategy needs to be one of {fundingStrategy} types.

Warnings

This call has no 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: Retrieve All Your Campaigns

This sample returns the details of the seller's campaign.

Input

There are no required inputs for this call. Optionally, you can use the campaign_name, campaign_status, end_date_range, limit, offset, and start_date_range fields to filter and control the size of the result set.

GEThttps://api.ebay.com/sell/marketing/v1/ad_campaign

Output

The output is a list of all the seller's campaigns.