Skip to main content

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. The request accepts either a listing_id, or an inventory_reference_id and inventory_reference_type pair, as used in the Inventory API.

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 method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.

Input

Resource URI (production)

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

URI parameters

ParameterTypeDescription
listing_idstringIdentifier of the eBay listing associated with the ad.

Occurrence: Conditional

inventory_reference_idstringThe seller's inventory reference ID of the listing to be used to find the campaign in which it is associated. This will either be a seller-defined SKU value or inventory item group ID, depending on the reference type specified. You must always pass in both inventory_reference_id and inventory_reference_type.

Occurrence: Conditional

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

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

{ /* Campaigns */
"campaigns" : [
{ /* Campaign */ }
]
}

Response fields

Output container/fieldTypeDescription
campaignsarray of Campaign

This is an array of one or campaigns that match the listing or inventory item group specified in the request.

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

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.

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.

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.brandsarray of string

An array of product brands used as an inclusion filter. A product's brand is defined in a listing's item specifics. This array will be returned if one or more product brands were used as a filter.

Occurrence: Conditional

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

The enumeration values returned in this field indicate if the category IDs in the corresponding categoryIds array are identifiers for eBay categories or for a seller's eBay store categories. This field is always returned if one or more category IDs are used as a filter.

Occurrence: Conditional

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

This array is only returned if one or more item condition values are used as a filter.

Note: Multiple listing condition IDs are mapped to the four valid values listed below. Refer to Promoted Listings Standard campaign flow for more details.

Valid Values:

  • 1000 = New
  • 2000 = Certified Refurbished
  • 2500 = Seller Refurbished
  • 3000 = Used

Occurrence: Conditional

campaigns.campaignCriterion.selectionRules.maxPriceAmount

Use this container to set a maximum price threshold. Any listings that have a 'Buy it Now' price above this price will not be considered for or added to this campaign.

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

Use this container to set a minimum price threshold. Any listings that have a 'Buy it Now' price below this price will not be considered for or added to this campaign.

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.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 shows the funding model used for the campaign, and the default bid percentage for a campaign that uses the Cost Per Sale (CPS) funding model.

Currently, the supported funding models are COST_PER_SALE and COST_PER_CLICK.

Occurrence: Always

campaigns.fundingStrategy.adRateStrategyAdRateStrategyEnum

The ad rate strategy that shall be applied to the campaign.

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. It is not used for campaigns that use the Cost Per Click (CPC) funding model.
Minimum value: 2.0
Maximum value: 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.
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

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
404Not Found
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.
35013API_MARKETINGREQUESTThe listing ID {listingId} is not valid.
35014API_MARKETINGREQUESTThe listing ID is required for this call.
35031API_MARKETINGREQUESTA 'listing_id' or an 'inventory_reference_id' and 'inventory_reference_type' is required for this call.
35032API_MARKETINGREQUESTA '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.

GEThttps://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.