openapi-directory

Version:

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

github.com/httptoolkit/openapi-directory-js

1 lines • 555 kB

JSON

{"openapi":"3.0.0","servers":[{"description":"Production","url":"https://api.ebay.com{basePath}","variables":{"basePath":{"default":"/sell/marketing/v1"}}}],"info":{"contact":{"name":"eBay Inc,","x-twitter":"ebay"},"description":"The Marketing API offers two platforms that sellers can use to promote and advertise their products: <ul><li>Promoted Listings is an eBay ad service that lets sellers set up ad campaigns for the products they want to promote. eBay displays the ads in search results and in other marketing modules as SPONSORED listings. If an item in a Promoted Listings campaign sells, the seller is assessed a Promoted Listings fee, which is a seller-specified percentage applied to the sales price. For complete details, refer to the <a href=\"/api-docs/sell/static/marketing/pl-landing.html\">Promoted Listings playbook</a>.</li><li>Promotions Manager gives sellers a way to offer discounts on specific items as a way to attract buyers to their inventory. Sellers can set up discounts (such as \"20% off\" and other types of offers) on specific items or on an entire customer order. To further attract buyers, eBay prominently displays promotion teasers throughout buyer flows. For complete details, see <a href=\"/api-docs/sell/static/marketing/promotions-manager.html\">Promotions Manager</a>.</li></ul> Marketing reports, on both the Promoted Listings and Promotions Manager platforms, give sellers information that shows the effectiveness of their marketing strategies. The data gives sellers the ability to review and fine tune their marketing efforts. Important! Sellers must have an active eBay Store subscription, and they must accept the Terms and Conditions before they can make requests to these APIs in the Production environment. There are also site-specific listings requirements and restrictions associated with these marketing tools, as listed in the \"requirements and restrictions\" sections for <a href=\"/api-docs/sell/marketing/static/overview.html#PL-requirements\">Promoted Listings</a> and <a href=\"/api-docs/sell/marketing/static/overview.html#PM-requirements\">Promotions Manager</a>. The table below lists all the Marketing API calls grouped by resource.","license":{"name":"eBay API License Agreement","url":"https://go.developer.ebay.com/api-license-agreement"},"title":"Marketing API","version":"v1.15.0","x-apisguru-categories":["ecommerce"],"x-logo":{"backgroundColor":"#FFFFFF","url":"https://twitter.com/ebay/profile_image?size=original"},"x-origin":[{"format":"openapi","url":"https://developer.ebay.com/api-docs/master/sell/marketing/openapi/3/sell_marketing_v1_oas3.json","version":"3.0"}],"x-providerName":"ebay.com","x-serviceName":"sell-marketing"},"paths":{"/ad_campaign":{"get":{"description":"This method retrieves the details for all of the seller's defined campaigns. Request parameters can be used to retrieve a specific campaign, such as the campaign's name, the start and end date, the status, and the funding model (Cost Per Sale (CPS) or Cost Per Click (CPC). 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.","operationId":"getCampaigns","parameters":[{"description":"Specifies 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","in":"query","name":"campaign_name","required":false,"schema":{"type":"string"}},{"description":"Include this filter and input a specific campaign status to retrieve campaigns currently in that state. Note: The results might not include all the campaigns with this status if other filters exclude them. Valid values: See <a href=\"/api-docs/sell/marketing/types/pls:CampaignStatusEnum\">CampaignStatusEnum</a> Maximum: 1 status","in":"query","name":"campaign_status","required":false,"schema":{"type":"string"}},{"description":"Specifies 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): <ul><li><code> yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ </code> (campaign ends within this range)</li><li><code>yyyy-MM-ddThh:mm:ssZ..</code> (campaign ends on or after this date)</li><li><code>..yyyy-MM-ddThh:mm:ssZ </code> (campaign ends on or before this date)</li><li><code>2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z</code> (campaign ends on September 08, 2016)</li></ul> Note: The results might not include all the campaigns ending on this date if other filters exclude them.","in":"query","name":"end_date_range","required":false,"schema":{"type":"string"}},{"description":"Specifies the funding strategy for the campaign. The results will be filtered to only include campaigns with the specified funding model. If not specified, all campaigns matching the other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them. Valid Values:<ul><li><code>COST_PER_SALE</code></li><li><code>COST_PER_CLICK</code></li></ul>","in":"query","name":"funding_strategy","required":false,"schema":{"type":"string"}},{"description":"Specifies the maximum number of campaigns to return on a page in the paginated response. Default: 10 Maximum: 500","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"Specifies 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 <code>0</code> and a limit of <code>10</code>, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is <code>10</code> and limit is <code>20</code>, the first page of the response contains items 11-30 from the complete result set. Default: 0","in":"query","name":"offset","required":false,"schema":{"type":"string"}},{"description":"Specifies 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): <ul><li><code>yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ</code> (starts within this range)</li><li><code>yyyy-MM-ddThh:mm:ssZ</code> (campaign starts on or after this date)</li><li><code>..yyyy-MM-ddThh:mm:ssZ </code>(campaign starts on or before this date)</li><li><code>2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z</code> (campaign starts on September 08, 2016)</li></ul> Note: The results might not include all the campaigns with this start date if other filters exclude them.","in":"query","name":"start_date_range","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignPagedCollectionResponse"}}},"description":"Success"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35020":{"category":"REQUEST","description":"The campaign name cannot be more than {maxCampaignNameLength} characters.","domain":"API_MARKETING"},"35023":{"category":"REQUEST","description":"The request contains invalid characters. {notAllowedCharacters} are not allowed.","domain":"API_MARKETING"},"35027":{"category":"REQUEST","description":"The date range {dateRange} is not valid. Ensure the beginning of the range is before the end of the range.","domain":"API_MARKETING"},"35028":{"category":"REQUEST","description":"The 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.","domain":"API_MARKETING"},"35029":{"category":"REQUEST","description":"The 'limit' has to be greater than zero and less than {maxLimitValue}.","domain":"API_MARKETING"},"35030":{"category":"REQUEST","description":"The 'offset' cannot be less than zero.","domain":"API_MARKETING"},"35043":{"category":"REQUEST","description":"The campaign status of {campaignStatus} is either invalid or not supported for this operation.","domain":"API_MARKETING"},"35079":{"category":"REQUEST","description":"Funding strategy needs to be one of {fundingStrategy} types.","domain":"API_MARKETING"}}}},"409":{"description":"Conflict","x-response-codes":{"errors":{"35077":{"category":"BUSINESS","description":"To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.","domain":"API_MARKETING"}}}},"500":{"description":"Internal Server error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing.readonly","https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["campaign"]},"post":{"description":"This method creates a Promoted Listings ad campaign. A Promoted Listings campaign is the structure into which you place the ads or ad group for the listings you want to promote. Identify the items you want to place into a campaign either by \"key\" or by \"rule\" as follows: <ul><li>Rules-based campaigns – A rules-based campaign adds items to the campaign according to the criteria you specify in your call to createCampaign. You can set the autoSelectFutureInventory request field to <code>true</code> so that after your campaign launches, eBay will regularly assess your new, revised, or newly-eligible listings to determine whether any should be added or removed from your campaign according to the rules you set. If there are, eBay will add or remove them automatically on a daily basis.</li> <li>Key-based campaigns – Add items to an existing campaign using either listing ID values or Inventory Reference values: <ul><li>Add listingId values to an existing campaign by calling either createAdByListingID or bulkCreateAdsByListingId.</li> <li>Add inventoryReference values to an existing campaign by calling either createAdByInventoryReference or bulkCreateAdsByInventoryReference.</li><li>Add an ad group to an existing campaign by calling createAdGroup.</li></ul>Note: No matter how you add items to a Promoted Listings campaign, each campaign can contain ads for a maximum of 50,000 items. If a rules-based campaign identifies more than 50,000 items, ads are created for only the first 50,000 items identified by the specified criteria, and ads are not created for the remaining items. Creating a campaign To create a basic campaign, supply: <ul><li>The user-defined campaign name</li> <li>The start date (and optionally the end date) of the campaign</li> <li>The eBay marketplace on which the campaign is hosted</li> <li>Details on the campaign funding model</li></ul> The campaign funding model specifies how the Promoted Listings fee is calculated. Currently, the supported funding models are <code>COST_PER_SALE</code> and <code>COST_PER_CLICK</code>. For complete information on how the fee is calculated and when it applies, see <a href=\"/api-docs/sell/static/marketing/pl-overview.html#pl-fees\">Promoted Listings fees</a>. If you populate the campaignCriterion object in your createCampaign request, campaign \"ads\" are created by \"rule\" for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign. For details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see <a href=\"/api-docs/sell/static/marketing/pl-create-campaign.html\">Promoted Listings campaign creation</a>. For recommendations on which listings are prime for a Promoted Listings ad campaign and to get guidance on how to set the bidPercentage field, see <a href=\"/api-docs/sell/static/marketing/pl-reco-api.html\">Using the Recommendation API to help configure campaigns</a>. Tip: See <a href=\"/api-docs/sell/marketing/static/overview.html#PL-requirements\">Promoted Listings requirements and restrictions</a> for the details on the marketplaces that support Promoted Listings via the API. See <a href=\"/api-docs/sell/static/marketing/pl-restrictions\">Promoted Listings restrictions</a> for details about campaign limitations and restrictions.","operationId":"createCampaign","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCampaignRequest","description":"This type defines the fields for the create campaign request."}}},"description":"This type defines the fields for the create campaign request.","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Created","headers":{"Location":{"schema":{"description":"The location response header contains the <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaign\">getCampaign</a> URI to the newly created campaign. The URL includes the eBay-assigned <code>campaignId</code>, which you can use to reference the campaign.","type":"string"}}},"x-response-codes":{"errors":{"35103":{"category":"BUSINESS","description":"This campaign has reached maximum capacity of {maxSupportedNumber} listings. To continue promoting listings, create a new campaign.","domain":"API_MARKETING"}}}},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35003":{"category":"REQUEST","description":"'campaignCriterion' is required for a criterion based campaign.","domain":"API_MARKETING"},"35004":{"category":"REQUEST","description":"One of the selectionRule containers is empty. You must specify at least one rule in each selectionRule container. Note: 'categoryScope' is not a rule.","domain":"API_MARKETING"},"35005":{"category":"REQUEST","description":"'selectionRules' is required for criterion based campaigns.","domain":"API_MARKETING"},"35006":{"category":"REQUEST","description":"'fundingStrategy' is required for this call.","domain":"API_MARKETING"},"35007":{"category":"REQUEST","description":"The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}.","domain":"API_MARKETING"},"35008":{"category":"REQUEST","description":"The category ID {categoryId} is not valid.","domain":"API_MARKETING"},"35009":{"category":"REQUEST","description":"The listing Condition ID {listingConditionId} is not valid. Refer to the API call documentation for a list of valid values.","domain":"API_MARKETING"},"35015":{"category":"REQUEST","description":"The 'maxPrice' or 'minPrice' value is missing or invalid. The value cannot be less than or equal to zero.","domain":"API_MARKETING"},"35016":{"category":"REQUEST","description":"The 'minPrice' {minPrice} cannot be greater than the 'maxPrice' {maxPrice}.","domain":"API_MARKETING"},"35017":{"category":"REQUEST","description":"'currency' is not valid or missing.","domain":"API_MARKETING"},"35019":{"category":"REQUEST","description":"Campaign name is required for this call.","domain":"API_MARKETING"},"35020":{"category":"REQUEST","description":"The campaign name cannot be more than {maxCampaignNameLength} characters.","domain":"API_MARKETING"},"35021":{"category":"REQUEST","description":"A campaign with the name of {campaignName} already exists. Please provide a different name.","domain":"API_MARKETING"},"35022":{"category":"REQUEST","description":"The brand name {brandName} is not valid.","domain":"API_MARKETING"},"35023":{"category":"REQUEST","description":"The request contains invalid characters. {notAllowedCharacters} are not allowed.","domain":"API_MARKETING"},"35024":{"category":"REQUEST","description":"The campaign start date {startDate} cannot be after the end date {endDate}.","domain":"API_MARKETING"},"35025":{"category":"REQUEST","description":"A campaign start date is required.","domain":"API_MARKETING"},"35026":{"category":"REQUEST","description":"A campaign start or end date {date} cannot be in the past.","domain":"API_MARKETING"},"35038":{"category":"REQUEST","description":"The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}.","domain":"API_MARKETING"},"35039":{"category":"REQUEST","description":"The 'categoryScope' is required for criterion based campaigns using category based listing selection rules. Valid values are: {categoryScopeValues}","domain":"API_MARKETING"},"35041":{"category":"REQUEST","description":"The 'marketplaceId' is required.","domain":"API_MARKETING"},"35042":{"category":"REQUEST","description":"The criterion type is required for criterion based campaigns. Valid values are: {criterionTypeValues}.","domain":"API_MARKETING"},"36101":{"category":"REQUEST","description":"The daily budget value format is a maximum of two decimal points.","domain":"API_MARKETING"}}}},"409":{"description":"Conflict","x-response-codes":{"errors":{"35051":{"category":"BUSINESS","description":"'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}.","domain":"API_MARKETING"},"35052":{"category":"BUSINESS","description":"The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings.","domain":"API_MARKETING"},"35053":{"category":"BUSINESS","description":"MarketplaceId: {marketplaceId} and Currency: {currency} for the listing selection rule do not match.","domain":"API_MARKETING"},"35067":{"category":"BUSINESS","description":"The seller must accept the Promoted Listing terms and conditions. For the requirements to use the Promoted Listing API, refer to the documentation.","domain":"API_MARKETING"},"35069":{"category":"BUSINESS","description":"No more than {maxNumberOfSelectionRules} listing selection rules are allowed in a campaign.","domain":"API_MARKETING"},"35072":{"category":"BUSINESS","description":"The number of listings that result from the rules exceeds the maximum number of listings allowed in a campaign, which is {maxSupportedNumber}. Refine the rules and submit the call again.","domain":"API_MARKETING"},"35074":{"category":"BUSINESS","description":"There were no eligible listings found for the selection rules provided. Please check the rules and submit the call again.","domain":"API_MARKETING"},"35075":{"category":"BUSINESS","description":"The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings.","domain":"API_MARKETING"},"35077":{"category":"BUSINESS","description":"To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.","domain":"API_MARKETING"},"35078":{"category":"BUSINESS","description":"To gain access to Promoted Listings, you must be in good standing with recent sales activity.","domain":"API_MARKETING"},"35089":{"category":"BUSINESS","description":"We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand.","domain":"API_MARKETING"},"35104":{"category":"BUSINESS","description":"'categoryScope' STORE can not be found. Please define the store categories first or use 'categoryScope' MARKETPLACE to select categories.","domain":"API_MARKETING"},"35106":{"category":"BUSINESS","description":"'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'.","domain":"API_MARKETING"},"35107":{"category":"BUSINESS","description":"'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'.","domain":"API_MARKETING"},"35108":{"category":"BUSINESS","description":"The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%.","domain":"API_MARKETING"},"35109":{"category":"BUSINESS","description":"The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%.","domain":"API_MARKETING"},"35110":{"category":"BUSINESS","description":"The 'adRateStrategy' is not supported for CPC funding model.","domain":"API_MARKETING"},"35111":{"category":"BUSINESS","description":"The 'dynamicAdRatePreferences' is not supported for CPC funding model.","domain":"API_MARKETING"},"35112":{"category":"BUSINESS","description":"The 'adRateStrategy' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True.","domain":"API_MARKETING"},"35114":{"category":"BUSINESS","description":"The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again.","domain":"API_MARKETING"},"36151":{"category":"BUSINESS","description":"'campaignCriterion' {campaignCriterion} is not supported for CPC funding model.","domain":"API_MARKETING"},"36152":{"category":"BUSINESS","description":"The 'bidPercentage' is not supported for CPC funding model.","domain":"API_MARKETING"},"36153":{"category":"BUSINESS","description":"The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}.","domain":"API_MARKETING"},"36154":{"category":"BUSINESS","description":"The daily budget below minimum allowed {minAllowed}.","domain":"API_MARKETING"},"36155":{"category":"BUSINESS","description":"The daily budget above maximum allowed {maxAllowed}.","domain":"API_MARKETING"},"36156":{"category":"BUSINESS","description":"campaignBudget is not supported for CPS funding model.","domain":"API_MARKETING"},"36157":{"category":"BUSINESS","description":"The daily budget is required for campaigns with CPC funding model.","domain":"API_MARKETING"},"36158":{"category":"BUSINESS","description":"The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places.","domain":"API_MARKETING"},"36159":{"category":"BUSINESS","description":"'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}.","domain":"API_MARKETING"}}}},"500":{"description":"Internal Server Error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["campaign"]}},"/ad_campaign/find_campaign_by_ad_reference":{"get":{"description":"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 <a href=\"/Devzone/XML/docs/Reference/eBay/index.html\" title=\"Trading API Reference\">Trading API</a> or the <a href=\"/api-docs/sell/inventory/resources/methods\">Inventory API</a> 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 <a href=\"/api-docs/sell/static/marketing/pl-overview.html#funding-model\">Funding Models</a> in the Promoted Listings Playbook for more information.","operationId":"findCampaignByAdReference","parameters":[{"description":"The 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.","in":"query","name":"inventory_reference_id","required":false,"schema":{"type":"string"}},{"description":"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.","in":"query","name":"inventory_reference_type","required":false,"schema":{"type":"string"}},{"description":"Identifier of the eBay listing associated with the ad.","in":"query","name":"listing_id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaigns"}}},"description":"Success"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35013":{"category":"REQUEST","description":"The listing ID {listingId} is not valid.","domain":"API_MARKETING"},"35014":{"category":"REQUEST","description":"The listing ID is required for this call.","domain":"API_MARKETING"},"35031":{"category":"REQUEST","description":"A 'listing_id' or an 'inventory_reference_id' and 'inventory_reference_type' is required for this call.","domain":"API_MARKETING"},"35032":{"category":"REQUEST","description":"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.","domain":"API_MARKETING"}}}},"404":{"description":"Not Found"},"409":{"description":"Business error"},"500":{"description":"Internal Server error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing.readonly","https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["campaign"]}},"/ad_campaign/get_campaign_by_name":{"get":{"description":"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 <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> to retrieve a list of the seller's campaign names.","operationId":"getCampaignByName","parameters":[{"description":"The name of the campaign.","in":"query","name":"campaign_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"description":"Success"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35019":{"category":"REQUEST","description":"Campaign name is required for this call.","domain":"API_MARKETING"},"35020":{"category":"REQUEST","description":"The campaign name cannot be more than {maxCampaignNameLength} characters.","domain":"API_MARKETING"},"35023":{"category":"REQUEST","description":"The request contains invalid characters. {notAllowedCharacters} are not allowed.","domain":"API_MARKETING"},"35046":{"category":"REQUEST","description":"No campaign found with the name {campaign_name}.","domain":"API_MARKETING"}}}},"404":{"description":"Not Found"},"409":{"description":"Business error"},"500":{"description":"Internal Server Error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing.readonly","https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["campaign"]}},"/ad_campaign/{campaign_id}":{"delete":{"description":"This method deletes the campaign specified by the <code>campaign_id</code> query parameter. Note: You can only delete campaigns that have ended. Call <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> to retrieve the campaign_id and the campaign status (<code>RUNNING</code>, <code>PAUSED</code>, <code>ENDED</code>, and so on) for all the seller's campaigns.","operationId":"deleteCampaign","parameters":[{"description":"A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. Note: You can retrieve the campaign IDs for a specified seller using the <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> method.","in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35045":{"category":"REQUEST","description":"No campaign found for campaign id {campaign_id}.","domain":"API_MARKETING"}}}},"404":{"description":"Not Found"},"409":{"description":"Conflict","x-response-codes":{"errors":{"35056":{"category":"BUSINESS","description":"The state of the campaign cannot be changed as requested.","domain":"API_MARKETING"},"35077":{"category":"BUSINESS","description":"To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.","domain":"API_MARKETING"},"35078":{"category":"BUSINESS","description":"To gain access to Promoted Listings, you must be in good standing with recent sales activity.","domain":"API_MARKETING"},"35089":{"category":"BUSINESS","description":"We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand.","domain":"API_MARKETING"}}}},"500":{"description":"Internal Server Error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["campaign"]},"get":{"description":"This method retrieves the details of a single campaign, as specified with the campaign_id query parameter. This method returns all the details of a campaign (including the campaign's the selection rules), except the for the listing IDs or inventory reference IDs included in the campaign. These IDs are returned by <a href=\"/api-docs/sell/marketing/resources/ad/methods/getAds\">getAds</a>. Call <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> to retrieve a list of the seller's campaign IDs.","operationId":"getCampaign","parameters":[{"description":"A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. Note: You can retrieve the campaign IDs for a specified seller using the <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> method.","in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}},"description":"Success"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35045":{"category":"REQUEST","description":"No campaign found for campaign id {campaign_id}.","domain":"API_MARKETING"}}}},"404":{"description":"Not Found"},"409":{"description":"Business error"},"500":{"description":"Internal Server Error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developers support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing.readonly","https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["campaign"]}},"/ad_campaign/{campaign_id}/ad":{"get":{"description":"This method retrieves Promoted Listings ads that are associated with listings created with either the <a href=\"/Devzone/XML/docs/Reference/eBay/index.html\" title=\"Trading API Reference\">Trading API</a> or the <a href=\"/api-docs/sell/inventory/resources/methods\" title=\"Inventory API Reference\">Inventory API</a>. The method retrieves ads related to the specified campaign. Specify the Promoted Listings campaign to target with the campaign_id path parameter. Because of the large number of possible results, you can use query parameters to paginate the result set by specifying a limit, which dictates how many ads to return on each page of the response. You can also specify how many ads to skip in the result set before returning the first result using the offset path parameter. Call <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> to retrieve the current campaign IDs for the seller.","operationId":"getAds","parameters":[{"description":"A comma-separated list of ad group IDs. The results will be filtered to only include active ads for these ad groups. Call <a href=\"/api-docs/sell/marketing/resources/adgroup/methods/getAdGroups\">getAdGroups</a> to retrieve the ad group ID for the ad group. Note: This field only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model.","in":"query","name":"ad_group_ids","required":false,"schema":{"type":"string"}},{"description":"A comma-separated list of ad statuses. The results will be filtered to only include the given statuses of the ad. If none are provided, all ads are returned.","in":"query","name":"ad_status","required":false,"schema":{"type":"string"}},{"description":"A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. Note: You can retrieve the campaign IDs for a specified seller using the <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> method.","in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}},{"description":"Specifies the maximum number of ads to return on a page in the paginated response. Default: 10 Maximum: 500","in":"query","name":"limit","required":false,"schema":{"type":"string"}},{"description":"A comma-separated list of listing IDs. The response includes only active ads (ads associated with a RUNNING campaign). The results do not include listing IDs that are excluded by other conditions.","in":"query","name":"listing_ids","required":false,"schema":{"type":"string"}},{"description":"Specifies the number of ads to skip in the result set before returning the first ad 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 <code>0</code> and a limit of <code>10</code>, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is <code>10</code> and limit is <code>20</code>, the first page of the response contains items 11-30 from the complete result set. Default: 0","in":"query","name":"offset","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdPagedCollectionResponse"}}},"description":"Success"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35013":{"category":"REQUEST","description":"The listing ID {listingId} is not valid.","domain":"API_MARKETING"},"35029":{"category":"REQUEST","description":"The 'limit' has to be greater than zero and less than {maxLimitValue}.","domain":"API_MARKETING"},"35030":{"category":"REQUEST","description":"The 'offset' cannot be less than zero.","domain":"API_MARKETING"},"35035":{"category":"REQUEST","description":"The campaign with campaign id {campaign_id} has ended.","domain":"API_MARKETING"},"35045":{"category":"REQUEST","description":"No campaign found for campaign id {campaign_id}.","domain":"API_MARKETING"},"35083":{"category":"REQUEST","description":"The requested 'adStatus' is not valid.","domain":"API_MARKETING"},"36106":{"category":"REQUEST","description":"The 'ad_group_ids' is not supported for CPS funding model.","domain":"API_MARKETING"}}}},"404":{"description":"Not Found"},"409":{"description":"Conflict","x-response-codes":{"errors":{"35068":{"category":"BUSINESS","description":"You have exceeded the maximum number of listing IDs. Only {maxSupportedNumber} listings are supported per call.","domain":"API_MARKETING"},"35077":{"category":"BUSINESS","description":"To use promoted listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.","domain":"API_MARKETING"}}}},"500":{"description":"Internal Server Error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing.readonly","https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["ad"]},"post":{"description":"This method adds a listing to an existing Promoted Listings campaign using a listingId value generated by the <a href=\"/Devzone/XML/docs/Reference/eBay/index.html\" title=\"Trading API Reference\">Trading API</a> or <a href=\"/api-docs/sell/inventory/resources/methods\" title=\"Inventory API Reference\">Inventory API</a>, or using a value generated by an ad group ID. For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.For the listing ID specified in the request, this method: <ul><li>Creates an ad for the listing.</li> <li>Sets the bid percentage (also known as the ad rate) for the ad.</li> <li>Associates the ad with the specified campaign.</li></ul> To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.For Promoted Listings Advanced (PLA) campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, an ad cannot be created.For the ad group specified in the request, this method associates the ad with the specified ad group.To create an ad for an ad group, specify the name of the ad group in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the <a href=\"/api-docs/sell/marketing/resources/adgroup/methods/createAdGroup\">createAdGroup</a> method. You can specify one or more ad groups per campaign.Use <a href=\"/api-docs/sell/marketing/resources/campaign/methods/createCampaign\">createCampaign</a> to create a new campaign and use <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> to get a list of existing campaigns.This call has no response payload. If the ad is successfully created, a <code>201 Created</code> HTTP status code and the <a href=\"/api-docs/sell/marketing/resources/ad/methods/getAd\">getAd</a> URI of the ad are returned in the location header.","operationId":"createAdByListingId","parameters":[{"description":"A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. Note: You can retrieve the campaign IDs for a specified seller using the <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> method.","in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAdRequest","description":"This request object defines the fields used in the createAdByListingId request."}}},"description":"This request object defines the fields used in the createAdByListingId request.","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Created","headers":{"Location":{"schema":{"description":"The location response header contains the getAd URI of the newly created ad. The URI includes the newly created <code>adID</code>, which you can use to reference the ad.","type":"string"}}}},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35007":{"category":"REQUEST","description":"The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}.","domain":"API_MARKETING"},"35010":{"category":"REQUEST","description":"The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign.","domain":"API_MARKETING"},"35013":{"category":"REQUEST","description":"The listing ID {listingId} is not valid.","domain":"API_MARKETING"},"35014":{"category":"REQUEST","description":"The listing ID is required for this call.","domain":"API_MARKETING"},"35035":{"category":"REQUEST","description":"The campaign with campaign id {campaign_id} has ended.","domain":"API_MARKETING"},"35036":{"category":"REQUEST","description":"An ad for listing ID {listingId} already exists.","domain":"API_MARKETING"},"35045":{"category":"REQUEST","description":"No campaign found for campaign id {campaign_id}.","domain":"API_MARKETING"},"35048":{"category":"REQUEST","description":"The listing ID {listingId} is invalid or has ended.","domain":"API_MARKETING"},"35080":{"category":"REQUEST","description":"The 'bidPercentage' is not supported for CPC funding model.","domain":"API_MARKETING"},"36106":{"category":"REQUEST","description":"The 'adGroupId' {adGroupId} is not supported for CPS funding model.","domain":"API_MARKETING"},"36210":{"category":"REQUEST","description":"No adgroup found for adgroup id {ad_group_id}.","domain":"API_MARKETING"},"36219":{"category":"REQUEST","description":"The ad group with ad_group id {ad_group_id} has been archived.","domain":"API_MARKETING"}}}},"404":{"description":"Not Found"},"409":{"description":"Business error","x-response-codes":{"errors":{"35052":{"category":"BUSINESS","description":"The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings.","domain":"API_MARKETING"},"35054":{"category":"BUSINESS","description":"The listing ID {listingId} was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace.","domain":"API_MARKETING"},"35057":{"category":"BUSINESS","description":"The listing ID {listingId} does not belong to the seller making this call.","domain":"API_MARKETING"},"35058":{"category":"BUSINESS","description":"The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing.","domain":"API_MARKETING"},"35059":{"category":"BUSINESS","description":"The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing.","domain":"API_MARKETING"},"35061":{"category":"BUSINESS","description":"The campaign with 'campaign_id' {campaign_id} is being synced to match the specifications of the campaign. Please wait a few minutes and try the call again.","domain":"API_MARKETING"},"35063":{"category":"BUSINESS","description":"The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends.","domain":"API_MARKETING"},"35064":{"category":"BUSINESS","description":"This operation is only supported for key based campaigns.","domain":"API_MARKETING"},"35075":{"category":"BUSINESS","description":"The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings.","domain":"API_MARKETING"},"35077":{"category":"BUSINESS","description":"To use Promoted Listings, you need to improve your seller level to Top Rated or Above Standard and have enough recent sales activity.","domain":"API_MARKETING"},"35078":{"category":"BUSINESS","description":"To gain access to Promoted Listings, you must be in good standing with recent sales activity.","domain":"API_MARKETING"},"35089":{"category":"BUSINESS","description":"We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand.","domain":"API_MARKETING"},"36221":{"category":"BUSINESS","description":"You have exceeded the maximum number of ads supported in a ad group with this request. Only {maxItemsLimit} ads are allowed per ad group.","domain":"API_MARKETING"}}}},"500":{"description":"Internal Server Error","x-response-codes":{"errors":{"35001":{"category":"APPLICATION","description":"There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance.","domain":"API_MARKETING"},"35002":{"category":"APPLICATION","description":"Internal error. Please wait a few minutes and try the call again.","domain":"API_MARKETING"}}}}},"security":[{"api_auth":["https://api.ebay.com/oauth/api_scope/sell.marketing"]}],"tags":["ad"]}},"/ad_campaign/{campaign_id}/ad/{ad_id}":{"delete":{"description":"This method removes the specified ad from the specified campaign. Pass the ID of the ad to delete with the ID of the campaign associated with the ad as path parameters to the call. Call <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> to get the current list of the seller's campaign IDs. 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 <a href=\"/api-docs/sell/static/marketing/pl-overview.html#funding-model\">Funding Models</a> in the Promoted Listings Playbook for more information. When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED.","operationId":"deleteAd","parameters":[{"description":"Identifier of an ad. This ID was generated when the ad was created.","in":"path","name":"ad_id","required":true,"schema":{"type":"string"}},{"description":"A unique eBay-assigned ID for an ad campaign that is generated when a campaign is created. Note: You can retrieve the campaign IDs for a specified seller using the <a href=\"/api-docs/sell/marketing/resources/campaign/methods/getCampaigns\">getCampaigns</a> method.","in":"path","name":"campaign_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"description":"Bad Request","x-response-codes":{"errors":{"35035":{"category":"REQUEST","description":"The campaign with campaign id {campaign_id} has ended.","domain":"API_MARKETING"},"35044":{"category":"REQUEST","description":"No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again.","domain":"API_MARKETING"},"35045":{"category":"REQUEST","description":"No campaign found for campaign id {campaign_id}.","doma