marketing APIv1.10.0

findCampaignByAdReference

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.

Input

Resource URI (production)

GET https://api.ebay.com/sell/marketing/v1/ad_campaign/find_campaign_by_ad_reference?

listing_id=string&

inventory_reference_id=string&

inventory_reference_type=string

URI parameters

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

HTTP request headers

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.

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

Copy complete valid JSON to Clipboard

{ /* Campaigns */

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

}

]

}

Response fields

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	Reserved for future use. Occurrence: Conditional
campaigns.campaignCriterion.criterionType	CriterionTypeEnum	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. Leave this field blank if you want to create campaign ads based on listing IDs. Occurrence: Conditional
campaigns.campaignCriterion.selectionRules	array of SelectionRule	Set 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.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. 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: See Category Changes for the latest list of category IDs. Retrieve a list of category IDs using the Taxonomy API. 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: Go to Seller Hub > Marketing. Click Manage store categories. A list of your store categories displays. 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.categoryScope	CategoryScopeEnum	Indicates the source of the category ID; eBay or seller's store. Occurrence: Conditional
campaigns.campaignCriterion.selectionRules.listingConditionIds	array of string	The 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.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. 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.value	string	The monetary amount in the specified currency. Required in the amount type. 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. 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.value	string	The monetary amount in the specified currency. Required in the amount type. 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 characters Occurrence: Conditional
campaigns.campaignStatus	CampaignStatusEnum	Indicates the status of the campaign, such as `RUNNING`, `PAUSED`, and `ENDED`. Occurrence: Conditional
campaigns.endDate	string	The 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.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 `COST_PER_SALE`. 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. 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.fundingModel	FundingModelEnum	Indicates 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.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 (`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

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

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 a Campaign by Item

This sample retrieves the campaign that is associated with item 5********2.

Input

The input for this call is the eBay listing ID.

GET

https://api.ebay.com/sell/marketing/v1/ad_campaign/find_campaign_by_ad_reference?listing_id=5********2

Output

The response provides the details of the campaign.

{
  "campaigns": [
    {
      "campaignCriterion": {
        "criterionType": "INVENTORY_PARTITION",
        "selectionRules": [
          {
            "categoryIds": [
              "1"
            ],
            "categoryScope": "STORE",
            "brands": [
              "gymboree"
            ],
            "minPrice": {
              "value": "2.0",
              "currency": "USD"
            },
            "maxPrice": {
              "value": "3.0",
              "currency": "USD"
            },
            "listingConditionIds": [
              "1000"
            ]
          }
        ],
        "autoSelectFutureInventory": false
      },
      "campaignId": "1********4",
      "campaignName": "Fall Sale",
      "campaignStatus": "SCHEDULED",
      "endDate": "2016-09-26T19:57:00.000Z",
      "fundingStrategy": {
        "fundingModel": "COST_PER_SALE",
        "bidPercentage": "10.0"
      },
      "startDate": "2016-09-25T02:20:00.000Z",
      "marketplaceId": "EBAY_US"
    }
  ]
}