marketing APIv1.10.0

getCampaigns

GET
/ad_campaign
This method retrieves the details for all the campaigns of a seller, including the campaign's the selection rules.

Note that this method does not return the listing IDs or inventory reference IDs of the items included in the ad campaign. Call getAds to retrieve these IDs.

You can filter the result set by a campaign name, end date range, start date range, 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 (production)

URI parameters

ParameterTypeDescription
campaign_statusstringSpecifies the campaign status. The results are filtered to include only campaigns that are in the specified states.

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_rangestringSpecifies 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 8, 2016)

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

Occurrence: Optional

end_date_rangestringSpecifies 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:00Z..2016-09-09T00:00:00Z   (campaign ends on September 8, 2016)

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

Occurrence: Optional

campaign_namestringSpecifies the campaign name. The results are filtered to include only the campaign by the specified name.

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

Maximum: 1 campaign name

Occurrence: Optional

limitstring

Specifies the maximum number of campaigns to return on a page in the paginated response.

Default: 10
Maximum: 500

Occurrence: Optional

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

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

Request fields

Output

HTTP response headers

Response payload

 Copy complete valid JSON to Clipboard
{ /* CampaignPagedCollection<Campaign> */
"campaigns" : [
{ /* Campaign */
"campaignCriterion" :
{ /* CampaignCriterion */
"autoSelectFutureInventory" : "boolean",
"criterionType" : "CriterionTypeEnum : [INVENTORY_PARTITION]",
"selectionRules" : [
{ /* SelectionRule */
"brands" : [
"string"
],
"categoryIds" : [
"string"
],
"categoryScope" : "CategoryScopeEnum : [MARKETPLACE,STORE]",
"listingConditionIds" : [
"string"
],
"maxPrice" :
{ /* Amount */
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
},
"minPrice" :
{ /* Amount */
"currency" : "CurrencyCodeEnum : [AED,AFN,ALL...]",
"value" : "string"
}
}
]
},
"campaignId" : "string",
"campaignName" : "string",
"campaignStatus" : "CampaignStatusEnum : [DELETED,ENDED,ENDING_SOON...]",
"endDate" : "string",
"fundingStrategy" :
{ /* FundingStrategy */
"bidPercentage" : "string",
"fundingModel" : "FundingModelEnum : [COST_PER_SALE]"
},
"marketplaceId" : "MarketplaceIdEnum : [EBAY_AT,EBAY_AU,EBAY_BE...]",
"startDate" : "string"
}
],
"href" : "string",
"limit" : "integer",
"next" : "string",
"offset" : "integer",
"prev" : "string",
"total" : "integer"
}

Response fields

Output container/fieldTypeDescription
campaignsarray of CampaignA list of campaigns contained on this page from the paginated response.

Occurrence: Conditional

campaigns.campaignCriterionCampaignCriterionThe selection rules (criterion) used to select the listings for a campaign.

Occurrence: Conditional

campaigns.campaignCriterion.autoSelectFutureInventorybooleanReserved for future use.

Occurrence: Conditional

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

Leave this field blank if you want to create campaign ads based on listing IDs.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRulesarray of SelectionRuleSet of rules that selects the listings to include in the campaign.

The following rules apply to the selection rules:

  • Each set of selection rules are ORed with each other.
  • Individual rules within a selection rule set are ANDed with each other. If a rule has a list of values (such a list of category IDs), the item need match only one of the values of the rule in order to be included in the campaign.

    • Note: If an item matches multiple sets of rules or multiple rules within a selection rule set, the item is considered only once.

Maximum number of rules: 10

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.brandsarray of stringA list of the brands of the items to be included in the campaign.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.categoryIdsarray of stringA list of category IDs associated with the listings to be included in the campaign. Ada 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:

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:

  1. Go to Seller Hub > Marketing.
  2. Click Manage store categories.
    A list of your store categories displays.
  3. 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.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.categoryScopeCategoryScopeEnumIndicates the source of the category ID; eBay or seller's store.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.listingConditionIdsarray of stringThe ID of the listing's condition. For more information, see Item condition ID and name values.

Note: As of September 1, 2021, condition ID 2500 ('Seller Refurbished') is no longer a valid item condition in the Cell Phones & Smartphones category (category ID 9355) for the following marketplaces: US, Canada, UK, Germany, and Australia. This refurbished item condition has been replaced by three new refurbished values, which include 'Excellent - Refurbished' (condition ID 2010), 'Very Good - Refurbished' (condition ID 2020), and 'Good - Refurbished' (condition ID 2030).

Note: In all eBay marketplaces, Condition ID 2000 now maps to an item condition of 'Certified - Refurbished', and not 'Manufacturer Refurbished'. To list an item as 'Certified Refurbished', a seller must be pre-qualified by eBay for this feature.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.maxPriceAmountThe maximum price of the listings included in the campaign.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.maxPrice.currencyCurrencyCodeEnumThe 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.valuestringThe monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.minPriceAmountThe minimum price of the listings included in the campaign.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.minPrice.currencyCurrencyCodeEnumThe 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.valuestringThe monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

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

Occurrence: Conditional

campaigns.campaignNamestringA 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: Conditional

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

Occurrence: Conditional

campaigns.endDatestringThe date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is blank (code>null), it indicates a campaign that has no end date. For display purposes, convert this time into the local time of the seller.

Occurrence: Conditional

campaigns.fundingStrategyFundingStrategyThis field specifies the funding model that defines how the Promoted Listing fee is calculated. The seller is assessed the fee if an item sells via a Promoted Listings action (such as buyer clicking on a Promoted Listings ad).

currently, the only funding model supported is COST_PER_SALE.

Occurrence: Conditional

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

bidPercentage is a single precision value that is guided by the following rules:
  • These values are valid:
       1,    1.0,    4.1,
       5.0,    5.5, ...
  • These values are not valid:
       0.01,    10.75,    99.99,
       and so on.

If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Minimum value: 1.0
Maximum value: 100.0

Occurrence: Conditional

campaigns.fundingStrategy.fundingModelFundingModelEnumIndicates the model that eBay uses to calculate the Promoted Listings fee. Currently, only COST_PER_SALE is supported.

Default: COST_PER_SALE

Occurrence: Conditional

campaigns.marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace where the campaign is hosted.

Occurrence: Conditional

campaigns.startDatestringThe 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: Conditional

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

Occurrence: Conditional

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

nextstringThe URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

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

prevstringThe URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

totalintegerThe total number of items retrieved in the result set.

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

Occurrence: Conditional

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.

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.
GET
https://api.ebay.com/sell/marketing/v1/ad_campaign

Output

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