Home
GET/ad_campaign/find_campaign_by_ad_reference
This method retrieves the campaigns containing the listing that is specified using either a listing ID, or an inventory reference ID and inventory reference type pair.
eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing.
An inventory reference ID can be either a seller-defined SKU or inventoryItemGroupKey, as specified in the Inventory API.
Note: This request accepts either a listing_id, or an inventory_reference_id and inventory_reference_type pair, as used in the Inventory API.
Parameter | Type | Description |
---|---|---|
listing_id | string | Identifier of the eBay listing associated with the ad. Occurrence: Optional |
inventory_reference_id | string | The seller's inventory reference ID of the listing to be used to find the campaign in which it is associated. You must always pass in both inventory_reference_id and inventory_reference_type. Occurrence: Optional |
inventory_reference_type | string | The type of the seller's inventory reference ID, which is a listing or group of items. You must always pass in both inventory_reference_id and inventory_reference_type. Occurrence: Optional |
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
This method has no additional required headers. See HTTP request headers- opens rest request components page for details.
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.
This call has no payload.
This call has no field definitions.
This call has no response headers.
Output container/field | Type | Description |
---|---|---|
campaigns | array of Campaign | An array of campaigns and their details. Occurrence: Conditional |
campaigns.campaignCriterion | CampaignCriterion | The selection rules (criterion) used to select the listings for a campaign. Occurrence: Conditional |
campaigns.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 |
campaigns.campaignCriterion.criterionType | CriterionTypeEnum | An enumerated value that defines the criterion (selection rule) types. Currently, the only criterion type supported is Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules | array of SelectionRule | A set of rules that selects the listings to include in the campaign. The following rules apply to the selection rules:
Note: If an item matches multiple sets of rules or multiple rules within a selection rule set, the item is considered only once. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.brands | array of string | A list of the brands of the items to be included in the campaign. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.categoryIds | array of string | 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
Seller store category IDs
Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.categoryScope | CategoryScopeEnum | Indicates the source of the category ID; eBay or seller's store. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.listingConditionIds | array of string | 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.
Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.maxPrice | Amount | The maximum price of the listings included in the campaign. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.maxPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.maxPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.minPrice | Amount | The minimum price of the listings included in the campaign. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.minPrice.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
campaigns.campaignCriterion.selectionRules.minPrice.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
campaigns.campaignId | string | A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created. Occurrence: Conditional |
campaigns.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: Conditional |
campaigns.campaignStatus | CampaignStatusEnum | Indicates the status of the campaign, such as Occurrence: Conditional |
campaigns.endDate | string | The date and time the campaign ends, in UTC format ( Occurrence: Conditional |
campaigns.fundingStrategy | FundingStrategy | This 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 Occurrence: Conditional |
campaigns.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. Minimum value: 1.0Maximum value: 100.0 Occurrence: Conditional |
campaigns.fundingStrategy.fundingModel | FundingModelEnum | Indicates the model that eBay uses to calculate the Promoted Listings fee. Currently, only Occurrence: Conditional |
campaigns.marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace where the campaign is hosted. Occurrence: Conditional |
campaigns.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: Conditional |
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 |
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. |
35013 | API_MARKETING | REQUEST | The listing ID {listingId} is not valid. |
35014 | API_MARKETING | REQUEST | The listing ID is required for this call. |
35031 | API_MARKETING | REQUEST | A 'listing_id' or an 'inventory_reference_id' and 'inventory_reference_type' is required for this call. |
35032 | API_MARKETING | REQUEST | A 'listing_id' and an 'inventory_reference_id' cannot be used together in the same call. To use both in a campaign, you must submit two calls. |
This call has no warnings.
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.
This sample retrieves the campaign that is associated with item 5********2.
The input for this call is the eBay listing ID.
GEThttps://api.ebay.com/sell/marketing/v1/ad_campaign/find_campaign_by_ad_reference?listing_id=5********2
The response provides the details of the campaign.