GET/ad_campaign/get_campaign_by_name
This method retrieves the details of a single campaign, as specified with the campaign_name query parameter. Note that the campaign name you specify must be an exact, case-sensitive match of the name of the campaign you want to retrieve.
Call getCampaigns to retrieve a list of the seller's campaign names.
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
Parameter | Type | Description |
---|---|---|
campaign_name | string | This query parameter specifies name of the campaign being retrieved. Use the getCampaigns method to retrieve a list of a seller's campaign names. Occurrence: Required |
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
Response fields
Output container/field | Type | Description |
---|---|---|
alerts | array of Alert | This array contains alert messages for the campaign. Occurrence: Conditional |
alerts.alertType | AlertTypeEnum | The type of alert message. For example, an invalid bid percentage. Occurrence: Conditional |
alerts.details | array of AlertDetails | A description of the alert including dimensions and aspects. Occurrence: Conditional |
alerts.details.dimension | AlertDimension | The dimension information of the alert including keys and values. Occurrence: Conditional |
alerts.details.dimension.key | DimensionKeyEnum | The key field of the applied dimension. For example, the marketplace Id. Occurrence: Conditional |
alerts.details.dimension.value | string | The value field of the applied dimension. For example, if the key is a Occurrence: Conditional |
alerts.details.aspect | Aspect | The aspect information of the alert including keys and values. Occurrence: Conditional |
alerts.details.aspect.key | AspectKeyEnum | The type of the aspect. For example, Occurrence: Conditional |
alerts.details.aspect.value | string | The value of the aspect. For example, if the aspect is a percentage, a value of '2.0' would equal 2%. Occurrence: Conditional |
budget | CampaignBudget | 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 |
budget.daily | Budget | The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign.
Occurrence: Conditional |
budget.daily.amount | Amount | The allocated budget amount for a CPC Promoted Listings campaign. Occurrence: Conditional |
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 |
budget.daily.budgetStatus | BudgetStatusEnum | The budget status for a CPC Promoted Listings campaign. Occurrence: Conditional |
campaignCriterion | CampaignCriterion | 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 |
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: Conditional |
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: Conditional |
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: Conditional |
campaignCriterion.selectionRules.maxPrice | Amount | This container sets the maximum price threshold. For more details, see Using the selectionRules container. Occurrence: Conditional |
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: Conditional |
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 |
campaignId | string | A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created. Occurrence: Always |
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: Always |
campaignStatus | CampaignStatusEnum | Indicates the status of the campaign, such as Occurrence: Always |
campaignTargetingType | CampaignTargetingTypeEnum | The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting ad campaign. Occurrence: Conditional |
channels | array of ChannelEnum | The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign.
Occurrence: Conditional |
endDate | string | The date and time the campaign ends, in UTC format ( Occurrence: Always |
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: Always |
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: Conditional |
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: Conditional |
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: Conditional |
fundingStrategy.dynamicAdRatePreferences.adRateAdjustmentPercent | string | The percentage above or below (-) the eBay suggested ad rate that a seller is willing to pay. Occurrence: Conditional |
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: Conditional |
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: Always |
marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace where the campaign is hosted. Occurrence: Always |
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: 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.
Status | Meaning |
---|---|
200 | Success |
400 | Bad Request |
404 | Not Found |
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. |
35019 | API_MARKETING | REQUEST | Campaign name is required for this call. |
35020 | API_MARKETING | REQUEST | The campaign name cannot be more than {maxCampaignNameLength} characters. |
35023 | API_MARKETING | REQUEST | The request contains invalid characters. {notAllowedCharacters} are not allowed. |
35046 | API_MARKETING | REQUEST | No campaign found with the name {campaign_name}. |
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 Campaign by its Name
This sample returns the details for the campaign named "Summer Sale."
Input
The input for this call is the campaign_name as a URI parameter.
GEThttps://api.ebay.com/sell/marketing/v1/ad_campaign/get_campaign_by_name?campaign_name=Summer Sale
Output
The output is the basic information about this campaign because there are no ads associated with the campaign yet.