The Marketing API offers two platforms that sellers can use to promote and advertise their products:
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.
Store Email Campaign allows sellers to create and send email campaigns to customers who have signed up to receive their newsletter. For more information on email campaigns, see Store Email Campaigns.
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 Promoted Listings and Promotions Manager.
The table below lists all the Marketing API calls grouped by resource.
", "contact": { "name": "eBay Inc," }, "license": { "name": "eBay API License Agreement", "url": "https://developer.ebay.com/join/api-license-agreement" }, "version": "v1.24.1" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/sell/marketing/v1" } } } ], "security": [ {} ], "paths": { "/ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference": { "post": { "tags": [ "ad" ], "description": "This method adds multiple listings that are managed with the Inventory API to an existing Promoted Listings campaign.For general strategy campaigns using the Cost Per Sale (CPS) funding model, bulk ads may be directly created for the listing.
For each listing ID specified in the request, this method:
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 ads with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.
You can specify a maximum of 500 listings per call and each campaign can have ads for a maximum of 50,000 items. Be aware when using this call that each variation in a multiple-variation listing creates an individual ad.
For manual targeting priority strategy 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, ads cannot be created.
Note: Ad groups are not required when adding listings to a smart targeting campaign.
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 plus the defaultBid for the ad 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 createAdGroup method.
You can specify one or more ad groups per campaign.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.
", "operationId": "bulkCreateAdsByListingId", "parameters": [ { "name": "campaign_id", "in": "path", "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associated the ads being created.ARCHIVED.",
"operationId": "bulkDeleteAdsByListingId",
"parameters": [
{
"name": "campaign_id",
"in": "path",
"description": "This path parameter specifies the eBay-assigned identifier of the ad campaign for which to delete a set of ads.The method updates the bidPercentage values for a set of ads associated with the specified campaign.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their associated updated bidPercentage values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference 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 Funding Models in the Promoted Listings Playbook for more information.", "operationId": "bulkUpdateAdsBidByInventoryReference", "parameters": [ { "name": "campaign_id", "in": "path", "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to update the bid percentage for a set of ads.The method updates the bidPercentage values for a set of ads associated with the specified campaign.
Specify the campaign_id as a path parameter and supply a set of listing IDs with their associated updated bidPercentage values in the request body. An eBay listing ID is generated when a listing is created with the Trading API.
Get the campaign IDs for a seller by calling getCampaigns and call getAds to get a list of the seller's inventory reference 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 Funding Models in the Promoted Listings Playbook for more information.", "operationId": "bulkUpdateAdsBidByListingId", "parameters": [ { "name": "campaign_id", "in": "path", "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to update the bid percentage for a set of ads.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.
To retrieve video ads preference information for each ad, set the fieldgroups query parameter to VIDEO.
Call getCampaigns to retrieve the current campaign IDs for the seller.
", "operationId": "getAds", "parameters": [ { "name": "ad_group_ids", "in": "query", "description": "A comma-separated list of ad group IDs. The results will be filtered to only include active ads for these ad groups.Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "fieldgroups", "in": "query", "description": "A comma-separated list of values that controls what is returned in the response. If not provided, standard ad fields are returned.For general strategy 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:
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 manual targeting priority strategy 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, ads cannot be created.
Note: Ad groups are not required when adding listings to a smart targeting campaign.
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 createAdGroup method.
You can specify one or more ad groups per campaign.
Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.
This call has no response payload. If the ad is successfully created, a 201 Created HTTP status code and the getAd URI of the ad are returned in the location header.
adID, which you can use to reference the ad."
},
"style": "simple",
"explode": false
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35007": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
},
"35010": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The bidPercentage should not be provided when selected adRateStrategy is DYNAMIC for the campaign."
},
"35013": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID {listingId} is not valid."
},
"35014": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID is required for this call."
},
"35035": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign with campaign id {campaign_id} has ended."
},
"35036": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "An ad for listing ID {listingId} already exists."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"35048": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID {listingId} is invalid or has ended."
},
"35080": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bidPercentage' is not supported for CPC funding model."
},
"36106": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The '{adGroupFieldName}' is not supported for CPS funding model."
},
"36152": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bidPercentage' is not supported for CPC funding model."
},
"36210": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No adgroup found for adgroup id {ad_group_id}."
},
"36219": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The ad group with ad group id {ad_group_id} has been archived."
},
"36412": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"35048": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID {listingId} is invalid or has ended."
},
"36210": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No ad group found for ad group id {ad_group_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35052": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
},
"35054": {
"domain": "API_MARKETING",
"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."
},
"35057": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The listing ID {listingId} does not belong to the seller making this call."
},
"35058": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The listing ID {listingId} is not a fixed price item. This is a requirement for a promoted listing."
},
"35059": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The listing ID {listingId} is not a multi-quantity item. This is a requirement for a promoted listing."
},
"35061": {
"domain": "API_MARKETING",
"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."
},
"35063": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
},
"35064": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This operation is only supported for key based campaigns."
},
"35075": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
},
"35077": {
"domain": "API_MARKETING",
"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."
},
"35078": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
},
"35089": {
"domain": "API_MARKETING",
"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."
},
"36221": {
"domain": "API_MARKETING",
"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."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_campaign/{campaign_id}/create_ads_by_inventory_reference": {
"post": {
"tags": [
"ad"
],
"description": "This method adds a listing that is managed with the Inventory API to an existing Promoted Listings campaign.In the request, supply the campaign_id and ad_id as path parameters.
To retrieve video ads preference information for the ad, set the fieldgroups query parameter to VIDEO.
Call getCampaigns to retrieve a list of the seller's current campaign IDs and call getAds to retrieve their current ad IDs.
", "operationId": "getAd", "parameters": [ { "name": "ad_id", "in": "path", "description": "This path parameter specifies the unique identifier of the ad being retrieved.ARCHIVED.",
"operationId": "deleteAd",
"parameters": [
{
"name": "ad_id",
"in": "path",
"description": "This path parameter specifies the unique identifier of the ad being deleted.The method deletes ads using a list of seller-defined inventory reference IDs, used with the Inventory API, that are associated with the specified campaign ID.
Specify the campaign ID (as a path parameter) and a list of inventoryReferenceId and inventoryReferenceType pairs to be deleted.
Call getCampaigns to get a list of the seller's current 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 Funding Models in the Promoted Listings Playbook for more information.ARCHIVED.",
"operationId": "deleteAdsByInventoryReference",
"parameters": [
{
"name": "campaign_id",
"in": "path",
"description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being deleted.INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.",
"required": true,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
},
{
"name": "inventory_reference_type",
"in": "query",
"description": "This query parameter specifies the type of the item the inventory_reference_id references.In the request, supply the campaign_id and ad_id as path parameters, and supply the new bidPercentage value in the payload of the call.
Call getCampaigns to retrieve a seller's current campaign IDs and call getAds to get their ad 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 Funding Models in the Promoted Listings Playbook for more information.", "operationId": "updateBid", "parameters": [ { "name": "ad_id", "in": "path", "description": "This path parameter specifies the unique identifier of the ad for which the bid percentage is being updated.0 and the limit is set to 10, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10 and the limit is set to 10, the method will retrieve items 11 through 20 from the list of items returned.0",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdGroupPagedCollectionResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35029": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
},
"35030": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'offset' cannot be less than zero."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35129": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This method is not supported for campaigns with smart targeting type."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
},
"post": {
"tags": [
"ad_group"
],
"description": "This method adds an ad group to an existing priority strategy campaign that uses manual targeting.adGroupID, which you can use to retrieve the ad group."
},
"style": "simple",
"explode": false
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35035": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign with campaign id {campaign_id} has ended."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"36201": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "An ad group with name {name} already exists for this campaign."
},
"36202": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The ad group name cannot be more than {maxAdGroupNameLength} characters."
},
"36203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' value {defaultBidValue} is not valid. The default bid value should be a double precision value."
},
"36204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' currency {defaultBidCurrency} is not valid or missing."
},
"36205": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' value {defaultBidValue} is below floor value {bidFloorValue}."
},
"36206": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' value {defaultBidValue} is above max value {bidMaxValue}."
},
"36207": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' value {defaultBidValue} is more than daily budget."
},
"36212": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' currency {defaultBidCurrency} should be the same as the daily budget."
},
"36214": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Ad Group name is required for this call."
},
"36215": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' is required for this call."
},
"36216": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'defaultBid' value is required for this call."
},
"36217": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The Ad Group name contains invalid characters. {notAllowedCharacters} are not allowed."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35089": {
"domain": "API_MARKETING",
"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."
},
"35129": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This method is not supported for campaigns with smart targeting type."
},
"36213": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The campaign funding model should be CPC. Please check funding model for provided campaign id."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_campaign/{campaign_id}/ad_group/{ad_group_id}": {
"get": {
"tags": [
"ad_group"
],
"description": "This method retrieves the details of a specified ad group, such as the ad group’s default bid and status.To clone a campaign, supply the campaign_id as a path parameter in your call. There is no request payload.
The ID of the newly-cloned campaign is returned in the Location response header.
Call getCampaigns to retrieve a seller's current campaign IDs.
Requirement: In order to clone a campaign, the campaignStatus must be ENDED and the campaign must define a set of selection rules (it must be a rules-based campaign).
You can filter the result set by a campaign name, end date range, start date range, campaign channel, 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": [ { "name": "campaign_name", "in": "query", "description": "This query parameter specifies the name of the campaign being retrieved. The results are filtered to include only the campaign by the specified name. yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (campaign ends within this range)yyyy-MM-ddThh:mm:ssZ.. (campaign ends on or after this date)..yyyy-MM-ddThh:mm:ssZ (campaign ends on or before this date)2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign ends on September 08, 2016)This query parameter specifies the maximum number of campaigns to return on a page in the paginated response.
Default: 100 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.yyyy-MM-ddThh:mm:ssZ..yyyy-MM-ddThh:mm:ssZ (starts within this range)yyyy-MM-ddThh:mm:ssZ (campaign starts on or after this date)..yyyy-MM-ddThh:mm:ssZ (campaign starts on or before this date)2016-09-08T00:00.00.000Z..2016-09-09T00:00:00Z (campaign starts on September 08, 2016)campaignId, which you can use to reference the campaign."
},
"style": "simple",
"explode": false
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"x-response-codes": {
"errors": {
"35103": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This campaign has reached maximum capacity of {maxSupportedNumber} listings. To continue promoting listings, create a new campaign."
},
"36410": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This campaign has been created with the suggested budget."
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35003": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'campaignCriterion' is required for a criterion based campaign."
},
"35004": {
"domain": "API_MARKETING",
"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."
},
"35005": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'selectionRules' is required for criterion based campaigns."
},
"35006": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'fundingStrategy' is required for this call."
},
"35007": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bidPercentage' {bidPercentage} is not valid. The bid percentage should be a single precision value. Minimum value: {minBidPercent} , Maximum value:{maxBidPercent}."
},
"35008": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The category ID {categoryId} is not valid."
},
"35009": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing Condition ID {listingConditionId} is not valid. Refer to the API call documentation for a list of valid values."
},
"35015": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxPrice' or 'minPrice' value is missing or invalid. The value cannot be less than or equal to zero."
},
"35016": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'minPrice' {minPrice} cannot be greater than the 'maxPrice' {maxPrice}."
},
"35017": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'currency' is not valid or missing."
},
"35019": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Campaign name is required for this call."
},
"35020": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
},
"35021": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
},
"35022": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The brand name {brandName} is not valid."
},
"35023": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
},
"35024": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign start date {startDate} cannot be after the end date {endDate}."
},
"35025": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign start date is required."
},
"35026": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign start or end date {date} cannot be in the past."
},
"35038": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}."
},
"35039": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'categoryScope' is required for criterion based campaigns using category based listing selection rules. Valid values are: {categoryScopeValues}."
},
"35041": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'marketplaceId' is required."
},
"35042": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The criterion type is required for criterion based campaigns. Valid values are: {criterionTypeValues}."
},
"35124": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxCpc' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}."
},
"35125": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bidPreferences' list currently supports only one element. Please remove additional elements and try again."
},
"35134": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A 'biddingStrategy' cannot be supplied for smart targeting campaigns. Please either remove 'biddingStrategy' from the request to create a smart targeting campaign or supply another value for 'campaignTargetingType'."
},
"36101": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The daily budget value format is a maximum of two decimal points."
},
"36158": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
},
"36161": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Smart targeting campaigns require a `bidPreferences.maxCpc` value."
},
"36162": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxCpc' currency should be the same as the daily budget."
},
"36163": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxCpc' value {maxCpcValue} is below minimum value {maxCpcMinimumValue}."
},
"36164": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxCpc' value {maxCpcValue} is above maximum value {maxCpcMaximumValue}."
},
"36165": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxCpc' value {maxCpcValue} is more than maximum daily budget {maxDailyBudget}."
},
"36166": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'maxCpc' value {maxCpcValue} is invalid. Refer to the API call documentation for more information."
},
"36406": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channels' value {channel} can only be used with the {funding_model} fundingModel."
},
"36407": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channels' value is invalid."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35051": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'marketplaceId' {marketplaceId} is not supported. Promoted Listings is supported only on these marketplaces: {supportedMarketplaces}."
},
"35052": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The category {categoryId} is not supported by the Promoted Listing service for multi-quantity listings."
},
"35053": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "MarketplaceId: {marketplaceId} and Currency: {currency} for the listing selection rule do not match."
},
"35067": {
"domain": "API_MARKETING",
"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."
},
"35069": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "No more than {maxNumberOfSelectionRules} listing selection rules are allowed in a campaign."
},
"35072": {
"domain": "API_MARKETING",
"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."
},
"35074": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "There were no eligible listings found for the selection rules provided. Please check the rules and submit the call again."
},
"35075": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The category {categoryId} is not supported by the Promoted Listing service for single-quantity listings."
},
"35077": {
"domain": "API_MARKETING",
"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."
},
"35078": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
},
"35089": {
"domain": "API_MARKETING",
"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."
},
"35094": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "Maximum number of campaigns allowed with the 'channels' value {channel} is exceeded."
},
"35095": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'marketplaceId' {marketplaceId} is not supported. Offsite Ads is supported only on these marketplaces: {supportedMarketplaces}."
},
"35104": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'categoryScope' STORE can not be found. Please define the store categories first or use 'categoryScope' MARKETPLACE to select categories."
},
"35106": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'BidPercentage' should be provided when selected 'adRateStrategy' is 'FIXED'."
},
"35107": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'dynamicAdRatePreferences' can be provided only when selected 'adRateStrategy' is 'DYNAMIC'."
},
"35108": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'adRateAdjustmentPercent' {adRateAdjustmentPercent} is not valid. Please set 'adRateAdjustmentPercent' {adRateAdjustmentPercent} between {minAllowedAdRateAdjustmentPercent}% - {maxAllowedAdRateAdjustmentPercent}%."
},
"35109": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'adRateCapPercent' {adRateCapPercent} is not valid. Please set 'adRateCapPercent' between {minAllowedAdRateCapPercent}% - {maxAllowedAdRateCapPercent}%."
},
"35110": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'adRateStrategy' is not supported for CPC funding model."
},
"35111": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'dynamicAdRatePreferences' is not supported for CPC funding model."
},
"35114": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'dynamicAdRatePreferences' list currently can only support one element containing dynamicAdRatePreference. Please remove additional elements and try again."
},
"35127": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'maxCPC' is only supported for CPC funding model campaigns with on-site channels and smart targeting type."
},
"35128": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'campaignTargetingType' is only supported for CPC funding model campaigns with on-site channels."
},
"35132": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'biddingStrategy' field is not supported for CPS funding model."
},
"35304": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "Another campaign cannot be created at this time, as the user is currently using a feature that only supports one campaign at a time."
},
"36151": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'campaignCriterion' {campaignCriterion} is not supported for CPC funding model."
},
"36152": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'bidPercentage' is not supported for CPC funding model."
},
"36153": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The daily budget currency {currency} is not supported for {fieldName}. The supported currency for the {marketplaceId} marketplace is {supportedCurrencyCode}."
},
"36154": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The daily budget below minimum allowed {minAllowed}."
},
"36155": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The daily budget above maximum allowed {maxAllowed}."
},
"36156": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "campaignBudget is not supported for CPS funding model."
},
"36157": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The daily budget is required for campaigns with CPC funding model."
},
"36158": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The daily budget value format {dailyBudgetValue} cannot have more than 2 decimal places."
},
"36159": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "'marketplaceId' {marketPlaceId} is not supported. Promoted Listings with CPC funding model is supported only on these marketplaces: {supportedMarketplaces}."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_campaign/{campaign_id}": {
"get": {
"tags": [
"campaign"
],
"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 getAds.
Call getCampaigns to retrieve a list of the seller's campaign IDs.
", "operationId": "getCampaign", "parameters": [ { "name": "campaign_id", "in": "path", "description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being retrieved.campaign_id query parameter.RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.",
"operationId": "deleteCampaign",
"parameters": [
{
"name": "campaign_id",
"in": "path",
"description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being deleted.RUNNING) or paused campaign. Specify the campaign you want to end by supplying its campaign ID in a query parameter. Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
RUNNING or PAUSED ad campaign that is being ended.INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.Call getCampaigns to retrieve a list of the seller's campaign names.
", "operationId": "getCampaignByName", "parameters": [ { "name": "campaign_name", "in": "query", "description": "This query parameter specifies name of the campaign being retrieved.You can restart the campaign by calling resumeCampaign, as long as the campaign's end date is in the future.
Note:The listings associated with a paused campaign cannot be added into another campaign.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.",
"operationId": "pauseCampaign",
"parameters": [
{
"name": "campaign_id",
"in": "path",
"description": "This path parameter specifies the unique eBay-assigned identifier of the RUNNING ad campaign being paused.
Use the getCampaigns method to retrieve campaign IDs.",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"204": {
"description": "No Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35035": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign with campaign id {campaign_id} has ended."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35056": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The state of the campaign cannot be changed as requested."
},
"35061": {
"domain": "API_MARKETING",
"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."
},
"35063": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
},
"35077": {
"domain": "API_MARKETING",
"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."
},
"35078": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
},
"35089": {
"domain": "API_MARKETING",
"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."
},
"35303": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The status of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_campaign/{campaign_id}/resume": {
"post": {
"tags": [
"campaign"
],
"description": "This method resumes a paused campaign, as long as its end date is in the future. Supply the campaign_id for the campaign you want to restart as a query parameter in the request.
Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
EBAY_US is used.null.0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.FIXEDDYNAMICFIXED bidding strategy.Specify the campaign_id you want to update as a URI parameter, and configure the campaignName and startDate in the request payload.
If you want to change only the end date of the campaign, specify the current campaign name, set endDate as desired, and set startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.
Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.
Call getCampaigns to retrieve a seller's campaign details, including the campaign ID, campaign name, and the start and end dates of the campaign.",
"operationId": "updateCampaignIdentification",
"parameters": [
{
"name": "campaign_id",
"in": "path",
"description": "This path parameter specifies the unique eBay-assigned identifier of the ad campaign being updated.
Use the getCampaigns method to retrieve campaign IDs.",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
},
{
"name": "Content-Type",
"in": "header",
"description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.
For more information, refer to HTTP request headers.",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"requestBody": {
"description": "This type defines the fields to update the campaign name and start and end dates.",
"content": {
"application/json": {
"schema": {
"description": "This type defines the fields to update the campaign name and start and end dates.",
"$ref": "#/components/schemas/UpdateCampaignIdentificationRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "No content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35019": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Campaign name is required for this call."
},
"35020": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign name cannot be more than {maxCampaignNameLength} characters."
},
"35021": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
},
"35023": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The request contains invalid characters. {notAllowedCharacters} are not allowed."
},
"35024": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign start date {startDate} cannot be after the end date {endDate}."
},
"35025": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign start date is required."
},
"35026": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign start or end date {date} cannot be in the past."
},
"35035": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign with campaign id {campaign_id} has ended."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35055": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The start date cannot be modified for an active campaign."
},
"35061": {
"domain": "API_MARKETING",
"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."
},
"35063": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The campaign with 'campaign_id' {campaign_id} is ending soon. No update operations are allowed on this campaign until it ends."
},
"35077": {
"domain": "API_MARKETING",
"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."
},
"35078": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "To gain access to Promoted Listings, you must be in good standing with recent sales activity."
},
"35089": {
"domain": "API_MARKETING",
"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."
},
"35306": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'endDate' of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
},
"35307": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'campaignName' of this campaign cannot be modified through this API. Refer to the API call documentation for more information."
},
"36408": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The seller must accept the new pricing policy before the campaign can be updated."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_campaign/{campaign_id}/bulk_create_keyword": {
"post": {
"tags": [
"keyword"
],
"description": "This method adds keywords, in bulk, to an existing priority strategy ad group in a campaign that uses manual targeting.
This method also sets the CPC rate for each keyword, depending on the selected bidding strategy, as follows:
FIXED: If the seller provides a keyword bid, that bid value will be used.DYNAMIC: The eBay suggested bid will be used.Specifies the maximum number of results to return on a page in the paginated response.
Default: 10Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordPagedCollectionResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailV3" } } }, "x-response-codes": { "errors": { "35029": { "domain": "API_MARKETING", "category": "REQUEST", "description": "The 'limit' has to be greater than zero and less than {maxLimitValue}." }, "35030": { "domain": "API_MARKETING", "category": "REQUEST", "description": "The 'offset' cannot be less than zero." }, "35045": { "domain": "API_MARKETING", "category": "REQUEST", "description": "No campaign found for campaign id {campaign_id}." }, "36314": { "domain": "API_MARKETING", "category": "REQUEST", "description": "Ad Group IDs should be delimited by {adGroupIdsDelimiter}." } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailV3" } } }, "x-response-codes": { "errors": { "35045": { "domain": "API_MARKETING", "category": "REQUEST", "description": "No campaign found for campaign id {campaign_id}." } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailV3" } } }, "x-response-codes": { "errors": { "35129": { "domain": "API_MARKETING", "category": "BUSINESS", "description": "This method is not supported for campaigns with smart targeting type." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetailV3" } } }, "x-response-codes": { "errors": { "35001": { "domain": "API_MARKETING", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance." }, "35002": { "domain": "API_MARKETING", "category": "APPLICATION", "description": "Internal error. Please wait a few minutes and try the call again." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/sell.marketing.readonly", "https://api.ebay.com/oauth/api_scope/sell.marketing" ] } ] }, "post": { "tags": [ "keyword" ], "description": "This method creates keywords using a specified campaign ID for an existing priority strategy campaign that uses manual targeting.keywordId, which you can use to reference the keyword."
},
"style": "simple",
"explode": false
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"x-response-codes": {
"errors": {
"35133": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The bid provided in the call was ignored because the selected biddingStrategy is DYNAMIC for the campaign."
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35035": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign with campaign id {campaign_id} has ended."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"36210": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No ad group found for ad group id {ad_group_id}."
},
"36219": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The ad group with ad group id {ad_group_id} has been archived."
},
"36301": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The keyword match type {matchType} is not supported. Valid values are: {matchTypeValues}."
},
"36303": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A keyword with text {keywordText} and match type {matchType} already exists for this Ad Group."
},
"36304": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters."
},
"36305": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bid' value {bidValue} is not valid. The default bid value should be a double precision value."
},
"36306": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bid' value {bidValue} is below floor value {bidFloorValue}."
},
"36307": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bid' value {bidValue} is above max value {bidMaxValue}."
},
"36308": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bid' currency {bidCurrency} is not valid or missing."
},
"36309": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bid' currency {bidCurrency} should be the same as the daily budget."
},
"36311": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The keywordText cannot be null or empty."
},
"36312": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The keywordText contains invalid characters {invalidCharacters}."
},
"36313": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"36210": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No ad group found for ad group id {ad_group_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35089": {
"domain": "API_MARKETING",
"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."
},
"35129": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This method is not supported for campaigns with smart targeting type."
},
"36319": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "You have exceeded the maximum number of create Keyword for an Ad Group. Only {maxSupportedNumber} IDs are supported per Ad Group."
},
"36320": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
},
"35002": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal error. Please wait a few minutes and try the call again."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_campaign/{campaign_id}/keyword/{keyword_id}": {
"get": {
"tags": [
"keyword"
],
"description": "This method retrieves details on a specific keyword from an ad group within a priority strategy campaign that uses the Cost Per Click (CPC) funding model.0 and the limit is set to 10, the method will retrieve items 1 through 10 from the list of items returned. If the offset is set to 10 and the limit is set to 10, the method will retrieve items 11 through 20 from the list of items returned.",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NegativeKeywordPagedCollectionResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35029": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'limit' has to be greater than zero and less than {maxLimitValue}."
},
"35030": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'offset' cannot be less than zero."
},
"36329": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The ad group ID is required."
},
"36347": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Currently only one value is supported for 'campaign_ids'."
},
"36350": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'negative_keyword_status' is invalid."
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35089": {
"domain": "API_MARKETING",
"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."
},
"35129": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This method is not supported for campaigns with smart targeting type."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
},
"post": {
"tags": [
"negative_keyword"
],
"description": "This method adds a negative keyword to an existing ad group in a priority strategy campaign that uses manual targeting.negativeKeywordId, which you can use to reference the negative keyword."
},
"style": "simple",
"explode": false
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35035": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign with campaign id {campaign_id} has ended."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"36210": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No ad group found for ad group id {ad_group_id}."
},
"36219": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The ad group with ad group id {ad_group_id} has been archived."
},
"36323": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Campaign."
},
"36330": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The provided negative keyword match type is not supported. Valid values are: {negativeKeywordMatchTypeValues}."
},
"36331": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'negativeKeywordText' {negativeKeywordText} and 'negativeKeywordMatchType' {negativeKeywordMatchType} already exists for this Ad Group."
},
"36332": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'negativeKeywordText' {negativeKeywordText} cannot be more than {maxNegativeKeywordTextLength} characters."
},
"36333": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'negativeKeywordText' cannot be null or empty."
},
"36334": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'negativeKeywordText' contains invalid characters {invalidCharacters}."
},
"36335": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You have exceeded the maximum number of negative keyword for an ad group. Only {maxSupportedNegativeKeywordNumber} IDs are supported per ad group."
},
"36336": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'negativeKeywordText' {negativeKeywordText} cannot have total number of words more than {maxWordsInNegativeKeyword} words."
},
"36345": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'campaignId' and 'adGroupId' are required."
},
"36346": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You have exceeded the maximum number of negative keyword for a campaign. Only {maxSupportedNegativeKeywordNumberCampaign} IDs are supported per campaign."
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
},
"36210": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No ad group found for ad group id {ad_group_id}."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35089": {
"domain": "API_MARKETING",
"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."
},
"35129": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This method is not supported for campaigns with smart targeting type."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/negative_keyword/{negative_keyword_id}": {
"get": {
"tags": [
"negative_keyword"
],
"description": "This method retrieves details on a specific negative keyword.yyyy-MM-ddThh:mm:ss.sssZ).Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
COST_PER_CLICK report metadata for a specific channel. Refer to the ChannelEnum type for supported values.COST_PER_CLICK funding model.",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReportMetadatas"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35121": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
},
"35125": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channel' is invalid. Valid values are: {supportedChannels}."
},
"35127": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channels' are not supported for the 'fundingModel' {fundingModel}."
}
}
}
},
"500": {
"description": "Internal Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/ad_report_metadata/{report_type}": {
"get": {
"tags": [
"ad_report_metadata"
],
"description": "This call retrieves metadata that details the fields used by a specific Promoted Listings report type. Use the report_type path parameter to indicate metadata to retrieve.COST_PER_CLICK funding model.",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReportMetadata"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35116": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Supplied 'report_type' not found. Valid values are: {supportedReportTypes}."
},
"35121": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
},
"35125": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channel' is invalid. Valid values are: {supportedChannels}."
},
"35127": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channels' are not supported for the 'fundingModel' {fundingModel}."
},
"35132": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channels' {supportedChannels} are not supported for the 'report_type' {reportType}."
},
"35133": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'fundingModel' is not supported for the 'report_type' {reportType}."
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35089": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You are currently not authorized to access the Promoted Listings Advanced program. Please contact support."
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/ad_report_task": {
"get": {
"tags": [
"ad_report_task"
],
"description": "This method returns information on all the existing report tasks related to a seller. Use the report_task_statuses query parameter to control which reports to return. You can paginate the result set by specifying a limit, which dictates how many report tasks to return on each page of the response. Use the offset parameter to specify how many reports to skip in the result set before returning the first result.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Combine offset with the limit query parameter to control the reports returned in the response. For example, if you supply an offset of 0 and a limit of 10, the response contains the first 10 reports from the complete list of report tasks retrieved by the call. If offset is 10 and limit is 10, the first page of the response contains reports 11-20 from the complete result set.
202, which indicates the report is being generated. Call getReportTasks (or getReportTask with the report-task ID) to determine the status of a Promoted Listings report. When a report is complete, eBay sets its status to SUCCESS and you can download it using the URL returned in the reportHref field of the getReportTask call. Report files are tab-separated value gzip files with a file extension of .tsv.gz.Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Important! The data threshold for a single report is currently 1 million records; if this threshold is exceeded, the report will fail.
reportTaskId, which you can use to reference the report task."
},
"style": "simple",
"explode": false
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35012": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'inventoryReferenceId' {inventoryReferenceId} is not valid."
},
"35013": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'listingId' {listingId} is not valid. Correct the 'listingId' and try the call again."
},
"35040": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'inventoryReferenceType' {inventoryReferenceType} is not supported."
},
"35041": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A 'marketplaceId' is required. Supported marketplaces are: {supportedMarketplaces}"
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for {campaignId}."
},
"35090": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "dateFrom and dateTo span exceeds maximum allowed. Only up to {maxDayRange} days are supported."
},
"35100": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Campaign ID is required for this call."
},
"35102": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The {date_key} date is required for this call."
},
"35103": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The date cannot be in future."
},
"35104": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The report start date {dateFrom} cannot be after the end date {dateTo}."
},
"35105": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The report 'dateFrom' {dateFrom} is out of range. Reports are limited up to {maxDays} days in the past."
},
"35106": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'dimensionKey' {dimensionKey} is not valid. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls."
},
"35107": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'dimensionKey' {dimensionKey} is not supported for the 'reportType' {reportType}. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls."
},
"35108": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'annotationKey' {annotationKey} is not supported for the 'dimensionKey' {dimensionKey}. To see the supported annotation and dimension keys for a report, use one of the 'Get Metadata' calls."
},
"35111": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'inventoryReferenceId' {inventoryReferenceId} is not valid."
},
"35113": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID is required for this call."
},
"35114": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'reportType' is invalid. Valid values are: {supportedReportTypes}."
},
"35115": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'metricKey' {metricKey} is not supported for the 'reportType' {reportType}. To see the supported metric keys for a report, use one of the 'Get Metadata' calls."
},
"35118": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'reportFormat' is missing or invalid. Valid values are: {supportedReportFormats}"
},
"35119": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The minimum set of 'dimensionKey' is not provided for the 'reportType' {reportType}. Minimum required dimensionKeys are: {minimumDimensionKeys}"
},
"35120": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "At least one 'metricKey' must be provided for 'reportType' {reportType}. Valid metricKeys are: {supportedMetricKeys}"
},
"35121": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'fundingModel' is invalid. Valid values are: {supportedFundingModels}."
},
"35122": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The metric key is not supported for the funding model."
},
"35123": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel}"
},
"35124": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Multiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}"
},
"35125": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channel' is invalid. Valid values are: {supportedChannels}."
},
"35126": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Multiple channels are not supported. Please use one of the following channels: {supportedChannels}"
},
"35127": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'channels' are not supported for the 'fundingModel' {fundingModel}"
},
"35128": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'dimensionKey' {dimensionKey} is not valid for the 'channels' {supportedChannels}"
},
"35129": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'metricKey' {metricKey} is not supported for the 'channels' {supportedChannels}"
},
"35130": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'annotationKey' {annotationKey} is not supported for the 'fundingModel' {fundingModel}."
},
"35131": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'annotationKey' {annotationKey} is not supported for the 'channels' {supportedChannels}"
},
"35137": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The {date_key} date format is not valid."
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35089": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You are currently not authorized to access the Promoted Listings Advanced program. Please contact support"
},
"35091": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'additionalRecords' are supported only with COST_PER_CLICK FundingModel and non-performing data is applicable for account level reports with no Day level dimension. 'additionalRecords' are applicable for reportTypes {supportedReportTypes}"
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35051": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'marketplaceId' {marketplaceId} is not supported. Supported marketplaces are: {supportedMarketplaces}"
},
"35068": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "You have exceeded the maximum number of listing IDs. Only {maxSupportedListings} listings are supported per call."
},
"35101": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "You have exceeded the maximum number of campaign IDs. Only {maxSupportedCampaigns} campaigns are supported per call."
},
"35112": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The maximum number {maxSupportedInventoryReferences} of inventory references has been exceeded."
}
}
}
},
"500": {
"description": "Internal Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/ad_report_task/{report_task_id}": {
"get": {
"tags": [
"ad_report_task"
],
"description": "This call returns the details of a specific Promoted Listings report task, as specified by the report_task_id path parameter. The report task includes the report criteria (such as the report dimensions, metrics, and included listing) and the report-generation rules (such as starting and ending dates for the specified report task).
Report-task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Report task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller's report-task IDs by calling getReportTasks.
Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.
Unlike an item discount, a markdown discount does not require the buyer meet a \"threshold\" before the offer takes effect. With markdown discounts, all the buyer needs to do is purchase the item to receive the discount benefit.
Important: There are some restrictions for which listings are available for price markdown discounts. For details, see Discounts Manager requirements and restrictions.
In addition, we recommend you list items at competitive prices before including them in your markdown discounts. For an extensive list of pricing recommendations, see the Growth tab in Seller Hub.
There are two ways to enable items for markdown discounts:
New discounts must be created in either a DRAFT or a SCHEDULED state. Use the DRAFT state when you are initially creating a discount and you want to be sure it's correctly configured before scheduling it to run. When you create a discount, the promotionId is returned in the Location response header. Use this ID to reference the discount in subsequent requests (such as to schedule a discount that's in a DRAFT state).
Tip: Refer to Discounts Manager in the Selling Integration Guide for details and examples showing how to create and manage seller discounts.
Markdown discounts are available on all eBay marketplaces. For more information, see Discounts Manager requirements and restrictions.
", "operationId": "createItemPriceMarkdownPromotion", "parameters": [ { "name": "Content-Type", "in": "header", "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemPriceMarkdown"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
},
"put": {
"tags": [
"item_price_markdown"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
},
{
"name": "Content-Type",
"in": "header",
"description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json. 1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"204": {
"description": "No Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
},
"345067": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A promotion can only be deleted if it is ended."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, please contact support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/item_promotion": {
"post": {
"tags": [
"item_promotion"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.eBay highlights discounted items by placing teasers for the discounted items throughout the online buyer flows.
Discounts are specified as either a monetary amount or a percentage off the standard sales price of a listing, letting you offer deals such as \"Buy 1 Get 1\" and \"Buy $50, get 20% off\".
Volume pricing discounts increase the value of the discount as the buyer increases the quantity they purchase.
Coded Coupons provide unique codes that a buyer can use during checkout to receive a discount. The seller can specify the number of times a buyer can use the coupon and the maximum amount across all purchases that can be discounted using the coupon. The coupon code can also be made public (appearing on the seller's Offer page, search pages, the item listing, and the checkout page) or private (only on the seller's Offer page, but the seller can include the code in email and social media).
Note: Coded Coupons are currently available in the US, UK, DE, FR, IT, ES, and AU marketplaces.
There are two ways to add items to a threshold discount:
You must create a new discount in either a DRAFT or SCHEDULED state. Use the DRAFT state when you are initially creating a discount and you want to be sure it's correctly configured before scheduling it to run. When you create a discount, the promotion ID is returned in the Location response header. Use this ID to reference the discount in subsequent requests.
Tip: Refer to the Selling Integration Guide for details and examples showing how to create and manage threshold discounts using the Discounts Manager.
For information on the eBay marketplaces that support item discounts, see Discounts Manager requirements and restrictions.
", "operationId": "createItemPromotion", "parameters": [ { "name": "Content-Type", "in": "header", "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemPromotionResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
},
"345076": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot get the details of a promotion that was not created through the API."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
},
"put": {
"tags": [
"item_promotion"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.Call getPromotions to retrieve the IDs of a seller's discounts.
When updating a discount, supply all the fields that you used to configure the original discount (and not just the fields you are updating). eBay replaces the specified discount with the values you supply in the update request and if you don't pass a field that currently has a value, the update request will fail.
The parameters you are allowed to update with this request depend on the status of the discount you're updating:
Tip: When updating a RUNNING or PAUSED discount, set the status field to SCHEDULED for the update request. When the discount is updated, the previous status (either RUNNING or PAUSED) is retained.
1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
},
{
"name": "Content-Type",
"in": "header",
"description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json. 1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"204": {
"description": "No Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
},
"38216": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A promotion can only be deleted if it is paused or ended."
},
"345077": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot update a promotion that was not created through the API."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, please contact support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/promotion/{promotion_id}/get_listing_set": {
"get": {
"tags": [
"promotion"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.The listing details are returned in a paginated set and you can control and results returned using the following query parameters: limit, offset, q, sort, and status.
Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "promotion_id", "in": "path", "description": "This path parameter takes a concatenation of the ID of the discount associated with the listing set plus the marketplace ID on which the discount is hosted. Concatenate the two values by separating them with an \"at sign\" (@).1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
},
{
"name": "q",
"in": "query",
"description": "Reserved for future use.",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
},
{
"name": "sort",
"in": "query",
"description": "Specifies the order in which to sort the associated listings in the response. If you precede the supplied value with a dash, the response is sorted in reverse order. sort=PRICE - Sorts the associated listings by their current price in ascending order sort=-TITLE - Sorts the associated listings by their title in descending alphabetical order (Z-Az-a) MARKED_DOWN, which indicates active markdown discounts.",
"required": false,
"schema": {
"type": "string",
"$ref": "#/components/schemas/ItemMarkdownStatusEnum"
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemsPagedCollection"
}
}
},
"x-response-codes": {
"errors": {
"345062": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Sort is not supported for this promotion type. For help, see the documentation for this call."
},
"345068": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The value of the 'Status' parameter is invalid. For help, see the documentation for this call."
},
"345069": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'Status' parameter is only supported for itemPriceMarkdownPromotions. For help, see the documentation for this call."
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
},
"38211": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The offset value must be an integer value greater than or equal to zero."
},
"38212": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The sort value was not valid. For the valid values, see the documentation for this call."
},
"38213": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You can query a limit of between 0 and 200 promotion records at a time. Update the request and resubmit the call."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing.readonly",
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/promotion": {
"get": {
"tags": [
"promotion"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.The call returns up to 200 currently-available discounts on the specified marketplace. While the response body does not include the discount's discountRules or inventoryCriterion containers, it does include the promotionHref (which you can use to retrieve the complete details of the discount).
Use query parameters to sort and filter the results by the number of discounts to return, the discount state or type, and the eBay marketplace. You can also supply keywords to limit the response to the discounts that contain that keywords in the title of the discount.
Maximum returned: 200
", "operationId": "getPromotions", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the maximum number of discounts returned on a page from the result set.Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "promotion_status", "in": "query", "description": "This parameter specifies the discount state by which you want to filter the results. The response contains only those discounts that match the state you specify.sort=END_DATE Sorts the discounts in the response by their end dates in ascending order sort=-PROMOTION_NAME Sorts the discounts by their name in descending alphabetical order (Z-Az-a) START_DATEEND_DATEPROMOTION_NAMERUNNING to PAUSED. Pausing a discount makes the discount temporarily unavailable to buyers and any currently-incomplete transactions will not receive the offer until the discount is resumed. Also, discount teasers are not displayed when a discount is paused. 1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
},
"38214": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A promotion can only be paused if it is scheduled or running."
},
"345077": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot update a promotion that was not created through the API."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/promotion/{promotion_id}/resume": {
"post": {
"tags": [
"promotion"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.PAUSED to RUNNING. Only discounts that have been previously paused can be resumed. Resuming a discount reinstates the teasers and any transactions that were in motion before the discount was paused will again be eligible for the discount. 1********5@EBAY_US",
"required": true,
"schema": {
"type": "string"
},
"style": "simple",
"explode": false
}
],
"responses": {
"204": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
},
"38204": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The seller is not eligible for promotions because they do not have an eBay Store or they have not accepted the terms and conditions for creating a promotion on this Marketplace, see the documentation for this call."
},
"38209": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot resume a promotion that is not paused or has already ended."
},
"345077": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot update a promotion that was not created through the API."
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38203": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Resource not found. Check the ID and try the call again."
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"38201": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
}
},
"/promotion_report": {
"get": {
"tags": [
"promotion_report"
],
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.
Default: 0
", "required": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "promotion_status", "in": "query", "description": "This parameter specifies the discount state by which you want to filter the results.RUNNING, PAUSED, and ENDED discounts (deleted reports are not returned) and summarizes the seller's campaign performance for all discounts on a given site. q query parameter.",
"operationId": "getEmailCampaigns",
"parameters": [
{
"name": "limit",
"in": "query",
"description": "The maximum number of email campaigns returned in a page.q=campaignType:WELCOME,ITEM_SHOWCASE will return only Welcome and Item Showcase email campaigns.campaignType value must be set through the q query parameter. If no other filters are set, all email campaigns for the specified campaign type(s) will be returned in the results set.",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
},
{
"name": "sort",
"in": "query",
"description": "The criteria for sorting email campaign results. See ItemSortEnum for sorting options and their enum values.NEWLY_LISTED",
"required": false,
"schema": {
"type": "string"
},
"style": "form",
"explode": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetEmailCampaignsResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35001": {
"domain": "STORE_CRM",
"category": "BUSINESS",
"description": "A store subscription is required for this call, please check the store subscription status for current seller."
},
"35301": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The paginated query limit {limit} value is missing or invalid. The value cannot be less than or equal to zero and also cannot be greater than maximum value."
},
"35302": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The paginated query offset {offset} value is missing or invalid. The value cannot be less zero and also cannot be greater than maximum value."
},
"35303": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The query string {q} is malformed. For the valid format, see the documentation for this call."
},
"35304": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The email campaign type {campaignType} in query string {q} is not supported. For the valid values, see the documentation for this call."
},
"35305": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The 'marketplaceId' in query string {q} is not supported. For the valid values, see the documentation for this call."
},
"35306": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The email campaign status {status} in query string {q} is not supported. For the valid values, see the documentation for this call."
},
"35307": {
"domain": "STORE_CRM",
"category": "REQUEST",
"description": "The campaign type {campaignType} in query string {q} is required."
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"x-response-codes": {
"errors": {
"35000": {
"domain": "STORE_CRM",
"category": "APPLICATION",
"description": "Internal server error encountered. If this problem persists, contact the eBay Developers Program for support."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
},
"post": {
"tags": [
"email_campaign"
],
"description": "This method creates a new email campaign. An eBay store owner can create six different types of email campaigns: Welcome, New products & collections, Coupon, Sale event + markdown, Order discount, and Volume pricing.EBAY-US corresponds to the United States market.sell/marketing/v1/email_campaign/report?startDate=2022-11-01T19:09:02.768Z&endDate=2022-12-28T19:09:02.768Ztrue enables video ads for any ads associated with the specified listing ID within the campaign, while false opts any ads associated with that listing ID within the campaign out of video ads. Note: Use this operation only for listings in Promoted Listings priority campaigns that use the Cost Per Click (CPC) funding model and already have a video attached to the listing. Video ads preferences are managed at the campaign level, not the ad group level. When a listing ID is opted into video ads for a given campaign, all ads associated with that listing ID within the campaign are opted into video ads.
To confirm the updated state, retrieve the affected ad or ads with the fieldgroups query parameter set to VIDEO so videoAdsPreferences is included in the response.
Note: A maximum of 500 listing IDs is supported per call.
Use bulkUpsertVideoAdsPreferences when you want to enable or disable video ads across several listings efficiently, rather than sending one request per listing. Setting videoAdsEnabled to true enables video ads for ads associated with the specified listing IDs within the campaign, while false opts those ads out of video ads.
Note: Use this operation only for listings in Promoted Listings priority campaigns that use the Cost Per Click (CPC) funding model and already have a video attached to the listing. Video ads preferences are managed at the campaign level, not the ad group level. When a listing ID is opted into video ads for a given campaign, all ads associated with that listing ID within the campaign are opted into video ads.
To confirm the updated state, retrieve the affected ad or ads with the fieldgroups query parameter set to VIDEO so videoAdsPreferences is included in the response.
ACTIVEPAUSEDARCHIVED4.1, 5.0, 5.5, ...0.01, 10.75, 99.99,2.0 and a maximum value of 100.0."
},
"inventoryReferenceId": {
"type": "string",
"description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
An inventoryItemGroupKey is a value that the seller defines to indicate a listing that's the parent of an inventory item group (a multiple-variation listing, such as a listing for a shirt that's available in multiple sizes and colors).
This field is only returned if the ad is associated with a SKU or an inventory item group value.
" }, "inventoryReferenceType": { "description": "The enumeration value returned here indicates the type of listing the inventoryReferenceId references. The value returned here will beINVENTORY_ITEM for a single-variation listing, or INVENTORY_ITEM_GROUP for a multiple-variation listing. This field is only returned if the ad is associated with a SKU or an inventory item group value.
", "$ref": "#/components/schemas/InventoryReferenceTypeEnum" }, "listingId": { "type": "string", "description": "A unique eBay-assigned ID that is generated when a listing is created." }, "videoAdsPreferences": { "$ref": "#/components/schemas/VideoAdsPreferences", "description": "A container for the details of video ads that are associated with an ad. This container is returned only when the fieldgroups query parameter is set toVIDEO."
}
},
"description": "A type that defines the fields for an ad."
},
"AdGroup": {
"type": "object",
"required": [
"adGroupId",
"adGroupStatus",
"defaultBid",
"name"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model."
},
"adGroupStatus": {
"description": "An enumeration value representing the current status of the ad group.ACTIVEPAUSEDARCHIVED0.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
},
"total": {
"type": "integer",
"description": "The total number of items retrieved in the result set.0.",
"format": "int32"
}
},
"description": "This type defines the details of a paged collection of ad groups.Default: 10",
"format": "int32"
},
"next": {
"type": "string",
"description": "The call URI that can be used to retrieve the next page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be increased to retrieve the next page of results.
Max length: 2048"
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first result on the current page. This value can be set in the request with the offset query parameter. If the offset value is not set, it defaults to zero.
Default: 0
Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
0.",
"format": "int32"
}
},
"description": "This type defines the fields that paginate the ads returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
},
"AdRateStrategyEnum": {
"type": "object",
"description": "An enumerated type that indicates the ad rate strategy for an existing Promoted Listings Standard (PLS) ad campaign. | - **DYNAMIC**: This enum value indicates that the ad rate is dynamically chosen for campaigns that use this ad rate strategy. - **FIXED**: This enum value indicates that the ad rate is fixed for campaigns that use this ad rate strategy.",
"enum": [
"DYNAMIC",
"FIXED"
]
},
"AdReference": {
"type": "object",
"required": [
"adId",
"href"
],
"properties": {
"adId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad. This ID is generated when an ad is created."
},
"href": {
"type": "string",
"description": "The getAd URI of an ad. You can use this URI to retrieve the ad."
}
},
"description": "This type defines the fields for an ad ID and its associated URL."
},
"AdReferences": {
"type": "object",
"properties": {
"ads": {
"type": "array",
"description": "A list of ad IDs. An ad ID is generated for each successfully created ad. Only one ad can be created per operation.",
"items": {
"$ref": "#/components/schemas/AdReference"
}
}
},
"description": "This type is a container for a list of ad IDs and their associated URIs."
},
"AdResponse": {
"type": "object",
"required": [
"listingId",
"statusCode"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a priority strategy campaign that uses the Cost Per Click (CPC) funding model.Note: This field will always be returned for campaigns that use the CPC funding model. It will not be returned for campaigns that use the Cost Per Sale (CPS) funding model."
},
"adId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad. This ID is generated when an ad is created.Note:This field is only returned when an ad is successfully created for the corresponding listing."
},
"errors": {
"type": "array",
"description": "An array of errors associated with the request.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"href": {
"type": "string",
"description": "The getAd URI that points to the ad.Note:This field is only returned when an ad is successfully created for the corresponding listing."
},
"listingId": {
"type": "string",
"description": "A unique eBay-assigned ID for a listing that is generated when the listing is created."
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code indicating if the corresponding ad was successfully created or not. 200 Successful should be returned for successfully created ads.Note:A status code is returned for each ad that the seller creates, or attempts to create.",
"format": "int32"
}
},
"description": "This type defines the fields returned in an ad response."
},
"AdStatusEnum": {
"type": "object",
"description": "An enumerated type that indicates the status of an existing ad. | - **ACTIVE**: This enum value indicates that the ad is active. - **PAUSED**: This enum value indicates that the ad is in the paused state. Ads can be moved back to the active state from the paused state. - **ARCHIVED**: This enum value indicates that the ad is in the archived state. Ads cannot be moved back to active state from the archived state. The ad must be recreated to become active.",
"enum": [
"ACTIVE",
"PAUSED",
"ARCHIVED"
]
},
"AdUpdateResponse": {
"type": "object",
"required": [
"listingId",
"statusCode"
],
"properties": {
"adId": {
"type": "string",
"description": "A unique eBay-assigned ID that is generated when the ad is created."
},
"errors": {
"type": "array",
"description": "A list of errors associated with the specified listing ID.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"href": {
"type": "string",
"description": "The URI for the ad, which can be used to retrieve the ad."
},
"listingId": {
"type": "string",
"description": "A unique eBay-assigned ID that is generated when the listing is created."
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code that indicates the response-status of the request.",
"format": "int32"
}
},
"description": "A type that contains the fields for the ad update response."
},
"AdUpdateStatusByListingIdResponse": {
"type": "object",
"required": [
"statusCode"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model."
},
"errors": {
"type": "array",
"description": "A list of errors associated with the specified listing ID.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"href": {
"type": "string",
"description": "The URI for the ad, which can be used to retrieve the ad."
},
"listingId": {
"type": "string",
"description": "A unique eBay-assigned ID that is generated when the listing is created."
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code that indicates the response-status of the request.",
"format": "int32"
}
},
"description": "A type that contains the fields for the ad update status by listing ID response."
},
"AdUpdateStatusResponse": {
"type": "object",
"required": [
"statusCode"
],
"properties": {
"adId": {
"type": "string",
"description": "A unique eBay-assigned ID that is generated when the ad is created."
},
"errors": {
"type": "array",
"description": "A list of errors associated with the specified listing ID.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"href": {
"type": "string",
"description": "The URI for the ad, which can be used to retrieve the ad."
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code that indicates the response-status of the request.",
"format": "int32"
}
},
"description": "A type that contains the fields for the ad update status response."
},
"AdditionalInfo": {
"type": "object",
"properties": {
"infoType": {
"description": "The type of additional information provided for the suggested keyword.KEYWORD_INSIGHTS",
"$ref": "#/components/schemas/AdditionalInfoEnum"
},
"metrics": {
"type": "array",
"description": "A list of additional data provided for the suggested keyword.",
"items": {
"$ref": "#/components/schemas/AdditionalInfoData"
}
}
},
"description": "A type that provides additional information for suggested keywords."
},
"AdditionalInfoData": {
"type": "object",
"properties": {
"metricKey": {
"description": "The metric used to provide additional information for the suggested keyword.ACTIVE_SELLER_COUNTSEARCH_VOLUMEMARKETPLACE_ID, the value would be from Marketplace ID values."
}
},
"description": "A type that contains the dimension fields."
},
"AlertTypeEnum": {
"type": "object",
"description": "An enumerated type used to define the alert type field. | - **INVALID_BID_PERCENTAGE**: This enum value indicates that the bid percentage is invalid. - **INVALID_CAP_PERCENTAGE**: This enum value indicates that the ad rate cap is invalid.",
"enum": [
"INVALID_BID_PERCENTAGE",
"INVALID_CAP_PERCENTAGE"
]
},
"Amount": {
"type": "object",
"properties": {
"currency": {
"description": "The base currency applied to the value field to establish a monetary amount. CAD",
"$ref": "#/components/schemas/CurrencyCodeEnum"
},
"value": {
"type": "string",
"description": "The monetary amount in the specified currency. MINIMUM_REQUIRED.",
"$ref": "#/components/schemas/AspectKeyEnum"
},
"value": {
"type": "string",
"description": "The value of the aspect. For example, if the aspect is a percentage, a value of '2.0' would equal 2%."
}
},
"description": "A type that contains the aspect fields."
},
"AspectKeyEnum": {
"type": "object",
"description": "An enumerated type used to define the aspect key field. | - **MINIMUM_REQUIRED**: This enum values indicates that the aspect key is minimum required value.",
"enum": [
"MINIMUM_REQUIRED"
]
},
"AudienceTypeEnum": {
"type": "object",
"description": "This enumerated type specifies the audience type of the email campaign. | - **ALL_SUBSCRIBERS**: All users subscribed to the seller store. - **NEW_SUBSCRIBERS**: All of the subscribers added to the seller store within the past 30 days. - **CUSTOM**: A custom audience created by the store seller. A custom audience is comprised of manually selected buyers. - **BUYER_GROUP**: A buyer group that has been created by the store seller to receive coded coupons. Buyer groups can be created for users to have bought from a specific category, within a specific timeframe, and for other parameters. - **FIRST_TIME_BUYERS**: All first time buyers from the seller store, regardless of when they made their first purchase. - **RECENT_BUYERS**: Buyers who have made a purchase from the eBay seller store between the last 31 - 365 days. - **MOST_RECENT_BUYERS**: Buyers who have made a purchase from the eBay seller store within the last 30 days. - **FOLLOWERS**: Followers of the eBay seller store. These are users who have saved the eBay seller. - **INTERESTED_BUYERS**: Those users who have marked that they are interested in a product from the seller store. - **NEW_FOLLOWERS**: All new followers of the seller store within the last 30 days. - **POST_CMPGN_NEW_BUYERS**: All users who became new buyers from the seller store after an email campaign.",
"enum": [
"ALL_SUBSCRIBERS",
"NEW_SUBSCRIBERS",
"CUSTOM",
"BUYER_GROUP",
"FIRST_TIME_BUYERS",
"RECENT_BUYERS",
"MOST_RECENT_BUYERS",
"FOLLOWERS",
"INTERESTED_BUYERS",
"NEW_FOLLOWERS",
"POST_CMPGN_NEW_BUYERS"
]
},
"BaseResponse": {
"type": "object",
"properties": {
"warnings": {
"type": "array",
"description": "The container for any warning error messages generated by the request. Warnings are not fatal in that they do not prevent the call from running and returning a response, but they should be reviewed to ensure your requests are returning the responses you expect.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"description": "This type defines the fields for any warning error messages."
},
"BidPreference": {
"type": "object",
"properties": {
"maxCpc": {
"description": "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.FIXED bidding strategy. ",
"enum": [
"FIXED",
"DYNAMIC"
]
},
"Budget": {
"type": "object",
"properties": {
"amount": {
"description": "The allocated budget amount for a CPC Promoted Listings campaign.",
"$ref": "#/components/schemas/Amount"
},
"budgetStatus": {
"description": "The budget status for a CPC Promoted Listings campaign.",
"$ref": "#/components/schemas/BudgetStatusEnum"
}
},
"description": "This type defines the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.ON_SITEOFF_SITEYou can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters" }, "campaignStatus": { "description": "Indicates the status of the campaign, such asRUNNING, PAUSED, and ENDED.",
"$ref": "#/components/schemas/CampaignStatusEnum"
},
"campaignTargetingType": {
"description": "The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting ad campaign.",
"$ref": "#/components/schemas/CampaignTargetingTypeEnum"
},
"channels": {
"type": "array",
"description": "The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign. ON_SITEOFF_SITEyyyy-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."
},
"fundingStrategy": {
"description": "This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.COST_PER_SALE (CPS) and COST_PER_CLICK (CPC). For onsite ads, the CPC model supports two bidding strategies: FIXED and DYNAMIC.",
"$ref": "#/components/schemas/FundingStrategy"
},
"marketplaceId": {
"description": "The ID of the eBay marketplace where the campaign is hosted.",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"startDate": {
"type": "string",
"description": "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.
" } }, "description": "This type defines the fields that describe an ad campaign." }, "CampaignAudience": { "type": "object", "required": [ "audienceType", "code", "name" ], "properties": { "audienceType": { "description": "This enum value indicates the audience type. For the complete list of audience types and their associated enum values, see AudienceTypeEnum.", "$ref": "#/components/schemas/AudienceTypeEnum" }, "code": { "type": "string", "description": "The unique code for an audience. " }, "name": { "type": "string", "description": "The display name for an audience." } }, "description": "This type defines the object for a single email campaign audience." }, "CampaignBudget": { "type": "object", "properties": { "daily": { "description": "The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign.50.00100.00true, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory.false"
},
"criterionType": {
"description": "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. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
0.",
"format": "int32"
}
},
"description": "This type defines the fields that paginate the campaigns returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
},
"CampaignStatusEnum": {
"type": "object",
"description": "This enumerated type is used to define the possible states of a campaign. | - **DELETED**: Indicates the campaign is deleted and is no longer accessible. Only ended campaigns can be deleted. - **DRAFT**: Indicates that the campaign is inactive and in draft status. - **ENDED**: Indicates the campaign has ended and it cannot be restarted. The listings associated with this campaign are not being promoted. - **ENDING_SOON**: Indicates a request to end the campaign was received and the system is going through the process of ending the campaign. No further operations are possible on this campaign until it ends. - **PAUSED**: Indicates the campaign has been paused and the listings in that campaign are not being promoted. Sellers can pause campaigns when they want to temporarily suspend a campaign. For example, a seller can pause a campaign if they go on vacation. The campaign can restored to a running state at any time. - **PENDING**: Indicates the campaign is a criterion-based campaign and is in process of being created. - **RUNNING**: Indicates the campaign is active. Listings included in the campaign are actively being promoted with sponsored ads, which are displayed to buyers as they search for items on eBay. - **SCHEDULED**: Indicates the campaign has been created, but it is scheduled to start on specific date in the future. - **SYSTEM_PAUSED**: Indicates a system-generated, temporary pause on the campaign due to the seller's level dropping to Below Standard. Below Standard sellers cannot create new campaigns or edit their existing campaigns, but they can still view their campaign data and download reports. Once their seller level improves to Above Standard or Top Rated, sellers can resume using Promoted Listings and their campaigns will be automatically unpaused and return their last status. For more details on returning their seller level to Above Standard or Top Rated, sellers can refer to their seller dashboard on the eBay platform. ",
"enum": [
"DELETED",
"DRAFT",
"ENDED",
"ENDING_SOON",
"PAUSED",
"PENDING",
"RUNNING",
"SCHEDULED",
"SYSTEM_PAUSED"
]
},
"CampaignTargetingTypeEnum": {
"type": "object",
"description": "This enumerated type is used to indicate the targeting type of an on-site priority strategy campaign. | - **MANUAL**: This enum value indicates that the campaign is a manual targeting campaign.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."
},
"fundingStrategy": {
"description": "This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.",
"$ref": "#/components/schemas/FundingStrategy"
},
"startDate": {
"type": "string",
"description": "The date and time the cloned 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.
" } }, "description": "This type defines the fields needed for a clone-campaign request." }, "CouponConfiguration": { "type": "object", "properties": { "couponCode": { "type": "string", "description": "A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay.CODED_COUPON."
},
"CouponTypeEnum": {
"type": "object",
"description": "This type indicates the type of Coded Coupon discount. It is required when the discount type is CODED_COUPON. | - **PRIVATE_SINGLE_SELLER_COUPON**: Anyone can use and share the coupon code, but it isn't posted on eBay. - **PUBLIC_SINGLE_SELLER_COUPON**: Anyone can find the coupon code on eBay and use it.",
"enum": [
"PRIVATE_SINGLE_SELLER_COUPON",
"PUBLIC_SINGLE_SELLER_COUPON"
]
},
"CreateAdGroupRequest": {
"type": "object",
"required": [
"defaultBid",
"name"
],
"properties": {
"defaultBid": {
"description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids.",
"$ref": "#/components/schemas/Amount"
},
"name": {
"type": "string",
"description": "The seller-defined name of the ad group."
}
},
"description": "A type that defines the fields for the CreateAdGroup request."
},
"CreateAdRequest": {
"type": "object",
"required": [
"listingId"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned identifier for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.4.1, 5.0, 5.5, ...0.01, 10.75, 99.99,2.0 and a maximum value of 100.0."
},
"listingId": {
"type": "string",
"description": "A unique identifier of an eBay listing."
}
},
"description": "This type defines the fields for the create ad request."
},
"CreateAdsByInventoryReferenceRequest": {
"type": "object",
"required": [
"inventoryReferenceId",
"inventoryReferenceType"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "Note: This field is not currently in use. Ad groups are only applicable to priority strategy ad campaigns that use the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information."
},
"bidPercentage": {
"type": "string",
"description": "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.4.1, 5.0, 5.5, ...0.01, 10.75, 99.99,2.0 and a maximum value of 100.0."
},
"inventoryReferenceId": {
"type": "string",
"description": "The unique identifier of a single-item listing or a multi-variation listing.INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API."
},
"inventoryReferenceType": {
"description": "This enumerated value indicates the type of item the inventoryReferenceId references.INVENTORY_ITEM or an INVENTORY_ITEM_GROUP.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
}
},
"description": "This type defines the fields needed to create ads by inventory reference ID request."
},
"CreateAdsByInventoryReferenceResponse": {
"type": "object",
"required": [
"ads",
"inventoryReferenceId",
"statusCode"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a priority strategy campaign that uses the Cost Per Click (CPC) funding model.Note: This field will always be returned for campaigns that use the CPC funding model. It will not be returned for campaigns that use the Cost Per Sale (CPS) funding model."
},
"ads": {
"type": "array",
"description": "A list of ad IDs. An ad ID is generated for each successfully created ad.",
"items": {
"$ref": "#/components/schemas/AdReference"
}
},
"errors": {
"type": "array",
"description": "An array of errors or warnings associated with the create-ads request.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"inventoryReferenceId": {
"type": "string",
"description": "An ID that identifies a single-item listing or multiple-variation listing that is managed with the Inventory API. The inventory reference ID is a seller-defined value that can be either an SKU for a single-item listing or an inventoryItemGroupKey for a multiple-value listing.
" }, "inventoryReferenceType": { "description": "Indicates the type of item the inventoryReferenceId references. The item can be either anINVENTORY_ITEM or an INVENTORY_ITEM_GROUP.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code that indicates the response-status of the request. Check this code to see if the ads were successfully created.",
"format": "int32"
}
},
"description": "This type defines the fields returned when you create an ad by inventory reference ID."
},
"CreateCampaignRequest": {
"type": "object",
"required": [
"campaignName",
"fundingStrategy",
"marketplaceId",
"startDate"
],
"properties": {
"budget": {
"description": "The allocated daily budget for the Cost Per Click (CPC) Promoted Listings campaign.You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters" }, "campaignTargetingType": { "description": "The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting campaign.MANUAL.MANUALSMARTON_SITE. Multiple channels are not supported. ON_SITEOFF_SITEOFF_SITE for a Promoted Offsite campaign.",
"items": {
"$ref": "#/components/schemas/ChannelEnum"
}
},
"endDate": {
"type": "string",
"description": "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."
},
"fundingStrategy": {
"description": "This container includes parameters that define an ad campaign funding strategy. The set of seller-configurable parameters depends on the selected fundingModel value.",
"$ref": "#/components/schemas/FundingStrategy"
},
"marketplaceId": {
"description": "The ID of the eBay marketplace where the campaign is hosted. See the MarketplaceIdEnum type to get the appropriate enumeration value for the listing marketplace.",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"startDate": {
"type": "string",
"description": "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.
" } }, "description": "This type defines the fields needed to create a campaign. To create a campaign, you need to specify a name, start and end dates, funding, marketplace, and optionally the criterion (selection rules)." }, "CreateEmailCampaignRequest": { "type": "object", "required": [ "audienceCodes", "emailCampaignType", "itemSelectMode", "personalizedMessage", "subject" ], "properties": { "audienceCodes": { "type": "array", "description": "An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no upper limit to the number of audience codes.AUTO in order to use a category ID."
},
"categoryType": {
"description": "This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to.",
"$ref": "#/components/schemas/CategoryTypeEnum"
},
"emailCampaignType": {
"description": "The email campaign type of the email campaign being created. There are six email campaigns that a user can create:WELCOME - an email sent automatically to new subscribers.ITEM_SHOWCASE - an email featuring new products & collections that the seller wants to highlight.COUPON - an email containing a coupon code and up to 4 items that this coupon can be applied to.ORDER_DISCOUNT - an email containing an order discount and up to 10 items that this discount can be applied to.SALE_EVENT - an email about a sale event and up to 10 items that the sale can be applied to.VOLUME_PRICING - an email containing up to 10 items that are eligible for volume pricing.COUPON campaign type is 4, and for every other campaign type is 10MANUAL in order to use this field.",
"items": {
"type": "string"
}
},
"itemSelectMode": {
"description": "Determines whether listings featured in an email campaign are selected by the seller or by eBay.AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.MANUAL, listings are set by the seller by populating the itemIds array.AUTO for WELCOME email campaigns.",
"$ref": "#/components/schemas/ItemSelectModeEnum"
},
"personalizedMessage": {
"type": "string",
"description": "The body of the email campaign. Accepts HTML and CSS.AUTO.",
"$ref": "#/components/schemas/PriceRange"
},
"promotionId": {
"type": "string",
"description": "The unique identifier of the discount used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT. promotionSelectModeEnum must set to MANUAL if a discount is selected.COUPON, SALE_EVENT, or ORDER_DISCOUNT.AUTO, eBay will choose the discount to include in the email campaign. If set to MANUAL, the seller must specify the discount in the promotionId field.",
"$ref": "#/components/schemas/PromotionSelectModeEnum"
},
"scheduleDate": {
"type": "string",
"description": "The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35ZAUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array. The following sort rules are available:ENDING_FIRST displays listings by ending date, from soonest to latest.LOWEST_PRICED displays listings by price, from lowest to highest.HIGHEST_PRICED displays listings by price, from highest to lowest.NEWLY_LISTED displays listings by date listed, with the newest first.NEWLY_LISTED.",
"$ref": "#/components/schemas/ItemSortEnum"
},
"subject": {
"type": "string",
"description": "The subject line of the email campaign.ACTIVE is returned for email campaigns that have been successfully created but not been sent.SENT is returned for email campaigns that have already been sent.ERROR is returned when an email has not been successfully created.",
"$ref": "#/components/schemas/EmailCampaignStatusEnum"
}
}
},
"CreateKeywordRequest": {
"type": "object",
"required": [
"adGroupId",
"keywordText",
"matchType"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "This adGroupId is created when an ad group is first created and associated with a campaign. This is the ad group that the corresponding keyword will be added to. This ad group must be a part of the campaign that is specified in the call URI. Use the getAdGroups method to retrieve the ad group IDs for a seller, and getKeywords to retrieve the keyword IDs for a seller's keywords."
},
"bid": {
"description": "This container is used to set the maximum bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged, at most, this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.BROADEXACTPHRASEEXACTPHRASENON_PERFORMING_DATA",
"items": {
"$ref": "#/components/schemas/AdditionalRecordEnum"
}
},
"campaignIds": {
"type": "array",
"description": "A list of campaign IDs to be included in the report task. Use the getCampaigns method to retrieve a list of the current campaign IDs for a seller.CAMPAIGN_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_SUMMARY_REPORT.ON_SITE. Multiple channels are not supported.ON_SITEOFF_SITEOFF_SITE if the report is for a Offsite Ads campaign.",
"items": {
"$ref": "#/components/schemas/ChannelEnum"
}
},
"dateFrom": {
"type": "string",
"description": "The date defining the start of the timespan covered by the report.[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z2021-03-15T13:00:00-07:00"
},
"dateTo": {
"type": "string",
"description": "The date defining the end of the timespan covered by the report.[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z2021-03-17T13:00:00-07:00"
},
"dimensions": {
"type": "array",
"description": "The list of the dimensions applied to the report. A dimension is an attribute to which the report data applies. For example, if you set dimensionKey to campaign_id in a Campaign Performance Report, the data will apply to the entire ad campaign. For information on the dimensions and how to specify them, see Promoted Listings reporting.
COST_PER_SALE.COST_PER_SALECOST_PER_CLICKINVENTORY_PERFORMANCE_REPORT.",
"items": {
"$ref": "#/components/schemas/InventoryReference"
}
},
"listingIds": {
"type": "array",
"description": "Use this field to supply an array of eBay listing IDs you want to include in the report.LISTING_PERFORMANCE_REPORT.Metrics are the quantitative measurements compiled into the report and the data returned is based on the specified dimension of the report. For example, if the dimension is campaign, the metrics for number of sales would be the number of sales in the campaign. However, if the dimension is listing, the number of sales represents the number of items sold in that listing.
For information on metric keys and how to set them, see Promoted Listings reporting.
Minimum: 1", "items": { "type": "string" } }, "reportFormat": { "description": "The file format of the report. Currently, the only supported format isTSV_GZIP, which is a gzip file with tab separated values.",
"$ref": "#/components/schemas/ReportFormatEnum"
},
"reportType": {
"description": "The type of report to be generated, such as ACCOUNT_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_REPORT.INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending.yyyy-MM-ddThh:mm:ss.sssZ - **INTEGER**: Indicates the data type of the value is integer. - **DOUBLE**: Indicates the data type of the value is double. - **STRING**: Indicates the data type of the value is string. - **LONG**: Indicates the data type of the value is long. ",
"enum": [
"DATE",
"INTEGER",
"DOUBLE",
"STRING",
"LONG"
]
},
"DeleteAdRequest": {
"type": "object",
"required": [
"listingId"
],
"properties": {
"listingId": {
"type": "string",
"description": "A unique eBay-assigned identifier for a listing that is generated when the listing is created. Note: This request accepts both listing IDs, as generated by the Inventory API, and an item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).
" } }, "description": "This type defines the fields used in a delete-ad request." }, "DeleteAdResponse": { "type": "object", "required": [ "adId", "listingId", "statusCode" ], "properties": { "adId": { "type": "string", "description": "The unique identifier of the ad that was deleted, or the ad that the seller attempted to delete." }, "errors": { "type": "array", "description": "An array of the errors or warnings associated with the request.", "items": { "$ref": "#/components/schemas/ErrorDetailV3" } }, "listingId": { "type": "string", "description": "A unique eBay-assigned ID for a listing that is generated when the listing is created." }, "statusCode": { "type": "integer", "description": "An HTTP status code that indicates the response-status of the request. Check this code to see if the ad was successfully deleted.Note:A status code is returned for each ad that the seller deletes, or attempts to delete.", "format": "int32" } }, "description": "This type defines the fields returned in a delete-ad response." }, "DeleteAdsByInventoryReferenceRequest": { "type": "object", "required": [ "inventoryReferenceId", "inventoryReferenceType" ], "properties": { "inventoryReferenceId": { "type": "string", "description": "The unique identifier of a single-item listing or a multi-variation listing.INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API."
},
"inventoryReferenceType": {
"description": "This enumerated value indicates the type of item the inventoryReferenceId references.INVENTORY_ITEM or an INVENTORY_ITEM_GROUP.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
}
},
"description": "This type defines the fields needed to delete an ad by its inventory reference ID. You must always supply both inventory_reference_id and inventory_reference_type."
},
"DeleteAdsByInventoryReferenceResponse": {
"type": "object",
"required": [
"adIds",
"inventoryReferenceId",
"inventoryReferenceType",
"statusCode"
],
"properties": {
"adIds": {
"type": "array",
"description": "The unique identifier of the ad that was deleted, or the ad that the seller attempted to delete.Note:Although the field name is plural and it is an array, only one ad ID will be returned here since there can be only one ad per listing.",
"items": {
"type": "string"
}
},
"errors": {
"type": "array",
"description": "The container for the errors associated with the request.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"inventoryReferenceId": {
"type": "string",
"description": "The inventory reference ID is a seller-defined SKU value for a single-item listing, or a seller-defined identifier for an inventory item group. Both of these values are defined when using the Inventory API, and an inventory item group is used to create a multiple-variation listing."
},
"inventoryReferenceType": {
"description": "The enumeration value returned here indicates if the ad was for a single-variation listing or a multiple-variation listing.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code indicating if the corresponding ad was successfully deleted or not. 200 Successful should be returned for successfully deleted ads. Note:A status code is returned for each ad that the seller deletes, or attempts to delete.",
"format": "int32"
}
},
"description": "This type defines the fields returned by request to delete a set of ads by inventory reference ID."
},
"DeleteEmailCampaignResponse": {
"type": "object",
"description": "This type defines the response payload for the deleteEmailCampaign method.",
"required": [
"emailCampaignId"
],
"properties": {
"emailCampaignId": {
"type": "string",
"description": "The unique eBay-assigned ID for the email campaign that is generated when the email campaign is created."
}
}
},
"Dimension": {
"type": "object",
"required": [
"dimensionKey"
],
"properties": {
"annotationKeys": {
"type": "array",
"description": "A list of annotations associated with the dimension of the report.",
"items": {
"type": "string"
}
},
"dimensionKey": {
"type": "string",
"description": "The name of the dimension on which the report is based. A dimension is an attribute to which the report data applies.
" } }, "description": "This type defines the annotation and dimension key used by the report. For information on how to set these values, see Promoted Listings reporting." }, "DimensionKeyAnnotation": { "type": "object", "required": [ "annotationKey", "dataType" ], "properties": { "annotationKey": { "type": "string", "description": "An annotation key associated with the dimension." }, "dataType": { "description": "The data type of the annotation key value.", "$ref": "#/components/schemas/DataTypeEnum" } }, "description": "This type defines the annotation values associated with a dimension. Annotations are metadata of the dimension. For example, annotations for a listing ID could belisting_title or listing_quantity_sold."
},
"DimensionKeyEnum": {
"type": "string",
"description": "An enumerated type used to define the dimension key field. | - **MARKETPLACE_ID**: This enum value indicates that the dimension key is marketplace ID. ",
"enum": [
"MARKETPLACE_ID"
]
},
"DimensionMetadata": {
"type": "object",
"required": [
"dataType",
"dimensionKey",
"dimensionKeyAnnotations"
],
"properties": {
"dataType": {
"description": "The data type of the dimension value used to create the report.",
"$ref": "#/components/schemas/DataTypeEnum"
},
"dimensionKey": {
"type": "string",
"description": "The name of the dimension used to create the report."
},
"dimensionKeyAnnotations": {
"type": "array",
"description": "An list of annotation keys associated with the specified dimension of the report.",
"items": {
"$ref": "#/components/schemas/DimensionKeyAnnotation"
}
}
},
"description": "This type defines the dimension used to create the report and the annotation keys associated with that dimension."
},
"DiscountBenefit": {
"type": "object",
"properties": {
"amountOffItem": {
"description": "The monetary amount that is discounted off an item (or items) when the discount criteria is met. 5, 6, 7, 8, 9, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65,
70, 75, 80, 85, 90, 95, 100/, 110,
120, 125, 150, 200, 250
For markdown discounts, the range is greater, as outlined below and detailed more precisely here: - $1 increments from $5 to $100
- $5 increments from $105 to $1,000
- $100 increments from $1,100 to $15,000
",
"$ref": "#/components/schemas/Amount"
},
"amountOffOrder": {
"description": "Used for threshold discounts, this is the monetary amount that is discounted off an order when the discount criteria is met. Because this field is valid only for orders, it's not a valid combination to use with markdown discounts.
Valid values for the associated amountOffOrder.value field:
5, 6, 7, 8, 9, 10, 15, 20, 25,
30, 35, 40, 45, 50, 55, 60, 65,
70, 75, 80, 85, 90, 95, 100, 110,
120, 125, 150, 200, 250",
"$ref": "#/components/schemas/Amount"
},
"percentageOffItem": {
"type": "string",
"description": "The percentage applied to the sales price that is discounted off the discounted item (or items) when the discount criteria is met.
Valid integer values for percentage off: Min: 5 Max: 80"
},
"percentageOffOrder": {
"type": "string",
"description": "Used for threshold discounts, this is the percentage of the order price that is discounted off the order when the discount criteria is met. This field is not value for markdown discounts.
Valid integer values for ORDER_DISCOUNT discounts: Min: 5 Max: 80
For VOLUME_DISCOUNT discounts: Must be set to 0 for the first discount rule."
}
},
"description": "This type defines the discount as either a monetary amount or a percentage of the sales price. Important!: You must populate one and only one of the fields in this container:
- amountOffItem
- amountOffOrder
- percentageOffItem
- percentageOffOrder
Tip: Refer to Configuring discounts for threshold discounts for information and examples on how to combine discountBenefit and discountSpecification values to create different types of discounts.
"
},
"DiscountRule": {
"type": "object",
"required": [
"discountBenefit",
"discountSpecification",
"maxDiscountAmount"
],
"properties": {
"discountBenefit": {
"description": "This container defines the discount as either a monetary amount or a percentage of the sales price. Note: When configuring discount benefits, populate just one of the following fields in the discountBenefit container:
- amountOffItem
- amountOffOrder
- percentageOffItem
- percentageOffOrder
For volume pricing, only percentageOffOrder is applicable as a discountBenefit. Also, the first discountBenefit container in a volume pricing configuration must set percentageOffOrder to 0.
Tip: Refer to Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
",
"$ref": "#/components/schemas/DiscountBenefit"
},
"discountSpecification": {
"description": "This container defines the criteria for when the discounts trigger, such as the minimum quantity that the buyer must purchase before the discount kicks in. The discount is applied each time the criteria defined by this container is met. When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container:
- minAmount
- minQuantity
- forEachQuantity
- forEachAmount
Important: When configuring volume pricing discounts, only minQuantity is applicable as a discountSpecification. Also, the configuration for minQuantity in a volume pricing configuration is specific. In the first discountSpecification container, set minQuantity to 1, and in the second, set minQuantity to 2. If you include a third discountRules pair, minQuantity must be set to 3, and in a fourth, it must be set to 4. Also, you must set a ruleOrder value in each discountRules container. In the first container, discountRules must be set to 1, and in each subsequent container, the value be be incremented by 1. For more, see Configuring volume pricing discounts.
Tip: see Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
",
"$ref": "#/components/schemas/DiscountSpecification"
},
"maxDiscountAmount": {
"description": "The limit on how much a buyer can save using a CODED_COUPON discount type. Permitted values are 1-1000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The Currency Code for 'maxDiscountAmount' must be the same as the Currency Code for 'budget'.
",
"$ref": "#/components/schemas/Amount"
},
"ruleOrder": {
"type": "integer",
"description": "This field indicates the order in which the discountRules are presented. The value specified for this field must equal the associated minQuantity value.
Required if you are creating a volume pricing discount.",
"format": "int32"
}
},
"description": "This complex type defines a discount as being either a monetary amount or a percentage of a sales price that's subtracted from the price of an item or order. Set the amount of the discount and the rules that govern when the discount triggers using the discountBenefit and discountSpecification fields.
Note: In volume pricing discounts, you must configure at least two discountRule containers and at most four.
"
},
"DiscountSpecification": {
"type": "object",
"properties": {
"forEachAmount": {
"description": "The monetary amount that must be spent on discounted items before the discount is applied.
Valid values for the associated forEachAmount value field:
5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
85, 89, 90, 95, 99, 100, 110, 120, 125,
149, 150, 175, 199, 200, 249, 250, 299,
300, 350, 399, 400, 450, 499, 500",
"$ref": "#/components/schemas/Amount"
},
"forEachQuantity": {
"type": "integer",
"description": "The number of items that must be purchased in order to qualify for the discount.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 1001, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 100",
"format": "int32"
},
"minAmount": {
"description": "Known as the \"threshold amount\", the minimum dollar amount that needs to be spent on discounted items in order to qualify for the discount.
Valid values for the associated minAmount value field:
5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
85, 89, 90, 95, 99, 100, 110, 120,
125, 149, 150, 175, 199, 200, 249, 250, 299,
300, 350, 399, 400, 450, 499, 500",
"$ref": "#/components/schemas/Amount"
},
"minQuantity": {
"type": "integer",
"description": "The minimum quantity of discounted items that needs to be bought in order to qualify for the discount.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
12, 13, 14, 15, 16, 17, 18, 19
20, 25, 50, 75, 100",
"format": "int32"
},
"numberOfDiscountedItems": {
"type": "integer",
"description": "Use this field to configure \"Buy One Get One\" (or BOGO) discounts.
You must couple this field with forEachQuantity and an amountOffItem or percentOffItem field to configure your BOGO discount. This field is not valid with order-based discounts.
The value of this field represents the number of items to be discounted when other discount criteria is met. For example, when the buyer adds the number of items identified by the forEachQuantity value to their cart, they are then eligible to receive the stated discount from an additional number of like items (the number of which is identified by this field) when they add those items to their cart. To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity plus the number indicated by this field.
Valid values:
1, 2, 3, 4, 5, 6, 7, 8, 9, 10",
"format": "int32"
}
},
"description": "This type defines the criteria for when the discounts trigger, such as the minimum quantity the buyer must purchase before the discount kicks in. The discount is applied each time the criteria defined by this container is met. Note: When configuring the rules that govern when the discounts are applied, populate just one of the following fields in the discountSpecification container:
- minAmount
- minQuantity
- forEachQuantity
- forEachAmount
Tip: Refer to Configuring threshold discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
"
},
"DynamicAdRatePreference": {
"type": "object",
"properties": {
"adRateAdjustmentPercent": {
"type": "string",
"description": "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."
},
"adRateCapPercent": {
"type": "string",
"description": "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."
}
},
"description": "A type that defines the ad rate details for a general strategy ad campaign."
},
"EmailCampaignStatusEnum": {
"type": "object",
"description": "This enumerated type indicates the current status of the email campaign. | - **ACTIVE**: The email campaign is active and ready to be sent. - **SENT**: The email campaign has been sent. - **ERROR**: There was an error when trying to create or update the email campaign. ",
"enum": [
"ACTIVE",
"SENT",
"ERROR"
]
},
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Identifies the type of error."
},
"domain": {
"type": "string",
"description": "Name for the primary system where the error occurred. This is relevant for application errors."
},
"errorId": {
"type": "integer",
"description": "A unique number to identify the error.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error."
},
"message": {
"type": "string",
"description": "Information on how to correct the problem, in the end user's terms and language where applicable."
},
"outputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
}
},
"description": "This type defines the fields that can be returned in an error."
},
"ErrorDetailV3": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as \"Seller does not ship item to Antarctica\" or \"Buyer ineligible to purchase an alcoholic item\". Business errors are not syntactical input errors.Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.
"
},
"domain": {
"type": "string",
"description": "Name of the domain containing the service or application."
},
"errorId": {
"type": "integer",
"description": "A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. For JSON, use JSONPath notation.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A detailed description of the condition that caused the error or warning and information on what to do to correct the problem. The string is normally 100-200 characters in length, but is not required to be such."
},
"message": {
"type": "string",
"description": "A short description of the condition that caused the error or warning. This value is at most 50 characters long and, if applicable, is localized in the end user's requested locale."
},
"outputRefIds": {
"type": "array",
"description": "An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. The path format is the same as inputRefId.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array that contains contextual information about the error or warning. The list often includes the parameter or input fields that triggered the warning or error condition.",
"items": {
"$ref": "#/components/schemas/ErrorParameterV3"
}
},
"subdomain": {
"type": "string",
"description": "The name of the subdomain in which the error or warning occurred. For example, checkout is a subdomain in the buying domain."
}
},
"description": "This type defines the fields returned in an error condition."
},
"ErrorParameter": {
"type": "object",
"description": "This type defines the parameters for an error.",
"properties": {
"name": {
"type": "string",
"description": "The object of the error."
},
"value": {
"type": "string",
"description": "The value of the object."
}
}
},
"ErrorParameterV3": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the entity that threw the error."
},
"value": {
"type": "string",
"description": "The value that was set for the element specified in the name field."
}
},
"description": "This type defines the parameters for an error."
},
"ExclusionsEnum": {
"type": "object",
"description": "An enumerated type used to filter keyword recommendations. | - **ADOPTED_KEYWORDS**: This enum value indicates that the keywords currently used for seller listings shall be considered in requests for keyword suggestions so that only new and unique keyword recommendations are provided.",
"enum": [
"ADOPTED_KEYWORDS"
]
},
"FundingModelEnum": {
"type": "string",
"description": "This enumerated type defines the funding models that specify how the Promoted Listing fee is calculated.
The seller is assessed a Promoted Listing fee only if an item sells via a Promoted Listing action. For more information, see Funding Models. | - **COST_PER_SALE**: This enum value indicates that the Promoted Listing fee is calculated by multiplying the bidPercentage by the final sales price of a transaction. - **COST_PER_CLICK**: This enum value indicates that the Promoted Listing fee is calculated on a Cost Per Click (CPC) basis.",
"enum": [
"COST_PER_SALE",
"COST_PER_CLICK"
]
},
"FundingStrategy": {
"type": "object",
"required": [
"fundingModel"
],
"properties": {
"adRateStrategy": {
"description": "This field is used to set the ad rate strategy for a Cost Per Sale (CPS) campaign.
The default value for this field is FIXED. If this field is omitted, the default value will be used.
Note: This field is not applicable for Cost Per Click (CPC) or offsite campaigns.",
"$ref": "#/components/schemas/AdRateStrategyEnum"
},
"biddingStrategy": {
"description": "Indicates the bidding strategy for an onsite Cost Per Click (CPC) campaign that uses manual targeting.
Note: This field is not applicable for smart targeting campaigns.
Valid values are:FIXED
When using a fixed bidding strategy, sellers manually assign and adjust keyword bids for the CPC campaign.DYNAMIC
When using a dynamic bidding strategy, eBay manages the campaign's keyword bids and automatically updates them daily to the suggested bid.
Note: For a CPC campaign using dynamic bidding, sellers can continue to manually add keywords for the campaign, but they are no longer able to manually adjust their associated bid values. In order to manually adjust bid values, sellers must use the FIXED bidding strategy.
Default value: FIXED",
"$ref": "#/components/schemas/BiddingStrategyEnum"
},
"bidPercentage": {
"type": "string",
"description": "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 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."
},
"bidPreferences": {
"type": "array",
"description": "This container indicates the bidding preferences of the campaign, such as the maximum CPC amount.
Note: This container is only applicable for smart targeting campaigns.
This container is required if the user wants to create a Smart Targeting campaign.",
"items": {
"$ref": "#/components/schemas/BidPreference"
}
},
"dynamicAdRatePreferences": {
"type": "array",
"description": "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 This field is not applicable for offsite campaigns.
Default: FIXED",
"items": {
"$ref": "#/components/schemas/DynamicAdRatePreference"
}
},
"fundingModel": {
"description": "Indicates the model that eBay uses to calculate the Promoted Listings fee. For a description of the funding model types, refer to FundingModelTypeEnum.",
"$ref": "#/components/schemas/FundingModelEnum"
}
},
"description": "This type defines how the Promoted Listings fee is calculated for a Promoted Listings ad campaign."
},
"GetEmailCampaignAudiencesResponse": {
"type": "object",
"description": "This type defines the response payload for the getAudiences method.",
"required": [
"audiences",
"href",
"limit",
"offset",
"total"
],
"properties": {
"audiences": {
"type": "array",
"description": "An array of audiences available for the specified email campaign type. If no audiences are available, the result will return an empty array.",
"items": {
"$ref": "#/components/schemas/CampaignAudience"
}
},
"href": {
"type": "string",
"description": "The URL to the current page of store email campaign audiences."
},
"limit": {
"type": "integer",
"description": "The value of the limit parameter submitted in the request, which is the maximum number of store email campaign audiences to return on a page from the result set.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
},
"offset": {
"type": "integer",
"description": "This value indicates the offset used for the current page of store email campaign audiences returned.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The URI for the previous page of results. This is returned if there is a previous page of results from the result set."
},
"total": {
"type": "integer",
"description": "The total number of available audiences returned under the query conditions.",
"format": "int32"
}
}
},
"GetEmailCampaignResponse": {
"type": "object",
"description": "This type defines the response payload for the getEmailCampaign method.",
"required": [
"audiences",
"creationDate",
"emailCampaignId",
"emailCampaignStatus",
"emailCampaignType",
"itemIds",
"itemSelectMode",
"marketplaceId",
"personalizedMessage",
"subject"
],
"properties": {
"audiences": {
"type": "array",
"description": "An array of one or more audiences associated with the email campaign.",
"items": {
"$ref": "#/components/schemas/CampaignAudience"
}
},
"categoryId": {
"type": "string",
"description": "The unique identifier of an eBay category or an eBay store category. This field is returned if a seller has applied the email campaign to a specific category.
The categoryType value will indicate if the category ID is for an eBay category or an eBay store category."
},
"categoryType": {
"description": "The enumeration value returned here indicates if the categoryId value is the identifier of an eBay category or an eBay store category.
This field is returned if a seller has applied the email campaign to a specific category.",
"$ref": "#/components/schemas/CategoryTypeEnum"
},
"creationDate": {
"type": "string",
"description": "The date and time that the email campaign was created, given in UTC format."
},
"emailCampaignId": {
"type": "string",
"description": "The unique identifier of the email campaign."
},
"emailCampaignStatus": {
"description": "The email campaign status. See EmailCampaignStatusEnum for a list of valid statuses.",
"$ref": "#/components/schemas/EmailCampaignStatusEnum"
},
"emailCampaignType": {
"description": "The email campaign type. See CampaignTypeEnum for valid email campaign types.",
"$ref": "#/components/schemas/CampaignTypeEnum"
},
"itemIds": {
"type": "array",
"description": "The listing IDs of the items that were manually added to the email campaign.
Only listings added manually by the seller are returned. Returns a null array if no listings were added.",
"items": {
"type": "string"
}
},
"itemSelectMode": {
"description": "The mode used to select the items listed in the email campaign.",
"$ref": "#/components/schemas/ItemSelectModeEnum"
},
"marketplaceId": {
"type": "string",
"description": "The eBay marketplace where the email campaign is active. See MarketplaceIdEnum for a list of marketplace IDs."
},
"modificationDate": {
"type": "string",
"description": "The date and time the email campaign was last modified, given in UTC format."
},
"personalizedMessage": {
"type": "string",
"description": "The body of the email campaign sent to the audience."
},
"priceRange": {
"description": "The price range and currency set within the email campaign. This container will only return if a price range was set.",
"$ref": "#/components/schemas/PriceRange"
},
"promotionId": {
"type": "string",
"description": "The ID of the discount that was assigned to the email campaign."
},
"promotionSelectMode": {
"description": "Indicates whether the listings that the discount was applied to were selected manually or automatically.
This field will only return if a discount was applied.",
"$ref": "#/components/schemas/PromotionSelectModeEnum"
},
"scheduleDate": {
"type": "string",
"description": "The date and time that the email campaign newsletter is scheduled to send, given in UTC format. This field is only returned if the seller set the start of the email campaign to a date in the future."
},
"scheduleDateType": {
"description": "The schedule type of the email campaign. See ScheduleDateTypeEnum.",
"$ref": "#/components/schemas/ScheduleDateTypeEnum"
},
"sentDate": {
"type": "string",
"description": "The date and time that the email campaign was sent, given in UTC format."
},
"sort": {
"description": "The sort rule is used to display the items in the email campaign. If no sort rule was selected, the default will be NEWLY_LISTED.",
"$ref": "#/components/schemas/ItemSortEnum"
},
"subject": {
"type": "string",
"description": "The email campaign subject."
}
}
},
"GetEmailCampaignsResponse": {
"type": "object",
"description": "This type defines the response payload of the getEmailCampaigns method.",
"required": [
"campaigns",
"href",
"limit",
"offset",
"total"
],
"properties": {
"campaigns": {
"type": "array",
"description": "A list of email campaigns that match the search criteria.",
"items": {
"$ref": "#/components/schemas/CampaignDTO"
}
},
"href": {
"type": "string",
"description": "The URL to the current page of store email campaigns."
},
"limit": {
"type": "integer",
"description": "The value of the limit parameter submitted in the request, which is the maximum number of store email campaigns to return on a page from the result set.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The URI for the next page of results. This value is returned if there is an additional page of results to return from the result set."
},
"offset": {
"type": "integer",
"description": "This value indicates the offset used for current page of store email campaigns being returned.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The URI for the previous page of results. This is returned if there is a previous page of results from the result set."
},
"total": {
"type": "integer",
"description": "Total number of available results returned under the filter criteria submitted in the request.",
"format": "int32"
}
}
},
"GetEmailPreviewResponse": {
"type": "object",
"description": "This type defines the response payload for the getEmailPreview method.",
"required": [
"content",
"renderDate"
],
"properties": {
"content": {
"type": "string",
"description": "The raw HTML code of the email campaign contents. The client side can use this HTML output directly.
Because the contents of an email campaign are subject to change, these contents are a \"snapshot\" of the email campaign at a specific time and date, indicated by the renderDate field."
},
"renderDate": {
"type": "string",
"description": "The date and time when a \"snapshot\" of the email campaign contents contained in the content result was taken. Given in UTC format."
}
}
},
"GetEmailReportResponse": {
"type": "object",
"description": "This type defines the response payload for the getEmailReport method.",
"required": [
"clickCount",
"openCount",
"totalSales"
],
"properties": {
"clickCount": {
"type": "integer",
"description": "The number of item listing links clicked from the body of campaign emails for the time range specified by the query.",
"format": "int32"
},
"openCount": {
"type": "integer",
"description": "The total email opened count for all email campaigns from a seller for the time range specified by the query.",
"format": "int32"
},
"totalSales": {
"description": "A seller's total sale amount for the time range specified by the query.",
"$ref": "#/components/schemas/Amount"
}
}
},
"InventoryCriterion": {
"type": "object",
"required": [
"inventoryCriterionType"
],
"properties": {
"inventoryCriterionType": {
"description": "Indicates how the items to be discounted are selected. You can include inventory by ID, using rules, or globally include all your inventory. ",
"$ref": "#/components/schemas/InventoryCriterionEnum"
},
"inventoryItems": {
"type": "array",
"description": "An array of containers for the seller's inventory reference IDs (also known as an \"SKU\" or \"custom label\") to be added to the discount.
Note: The request can have either inventoryItems or listingIds, but not both.
Maximum: 2000 parent items
Maximum SKU or custom label length: 50 characters
Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds.",
"items": {
"$ref": "#/components/schemas/InventoryItem"
}
},
"listingIds": {
"type": "array",
"description": "An array of eBay listing IDs to be discounted.
Note: The request can have either inventoryItems or listingIds, but not both.
Required: All listings being discounted must offer an electronic payment method.
Maximum: 2000 parent items
Maximum SKU or custom label length: 50 characters
Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds.",
"items": {
"type": "string"
}
},
"ruleCriteria": {
"description": "This container defines a set of inventory selection rules for a discount.
When defining rule criteria, you must limit item exclusions to 100 IDs when you choose from live inventory.
Required if InventoryCriterionEnum is set to INVENTORY_BY_RULE or INVENTORY_ANY.",
"$ref": "#/components/schemas/RuleCriteria"
}
},
"description": "This type defines either the selections rules or the list of listing IDs for the discount. The \"listing IDs\" are either the seller's item IDs or the eBay listing IDs."
},
"InventoryCriterionEnum": {
"type": "object",
"description": "This enumerated type defines the values that represent the inventory selection method for a discount. | - **INVENTORY_BY_RULE**: Indicates the discount inventory selection is based on rules and item aspects such as item condition or brand.
Note: If inventoryCriterionType is set to this value, the request payload must have at least one rule in ruleCriteria. - **INVENTORY_BY_VALUE**: Indicates the discount inventory selection is either a list of the seller's inventory reference IDs (also known as an \"SKU\" or \"custom label\") or eBay listing IDs.
Note: If inventoryCriterionType is set to this value, the request payload must have at least one listing ID in listingIds or inventoryItems. - **INVENTORY_ANY**: Indicates all the seller's inventory is discounted.
Note: If inventoryCriterionType is set to this value, include an inventory selection rule. In the request payload, use ruleCriteria that contains criteria or null.",
"enum": [
"INVENTORY_BY_RULE",
"INVENTORY_BY_VALUE",
"INVENTORY_ANY"
]
},
"InventoryItem": {
"type": "object",
"properties": {
"inventoryReferenceId": {
"type": "string",
"description": "The unique identifier of a single-item listing or a multi-variation listing.
To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify and item ID or a SKU (if the SKU is defined in the listing)
To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API."
},
"inventoryReferenceType": {
"description": "Indicates the type of the inventoryReferenceId, which can be either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.
Note: This value is not currently returned in the response.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
}
},
"description": "This type defines the fields for the seller inventory reference IDs (also known as an \"SKU\" or \"custom label\")."
},
"InventoryReference": {
"type": "object",
"properties": {
"inventoryReferenceId": {
"type": "string",
"description": "The unique identifier of a single-item listing or a multi-variation listing.
To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).
To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.
Required if if you supply an inventoryReferenceType."
},
"inventoryReferenceType": {
"description": "Indicates the type of item indicated by the inventoryReferenceId.
This value can be set to either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.
Required if if you supply an inventoryReferenceId.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
}
},
"description": "This complex type is used to identify an item that is managed by the Inventory API. The type defines the fields contained in an inventory reference ID."
},
"InventoryReferenceTypeEnum": {
"type": "string",
"description": "An enumerated type defining the type of the seller's inventory reference ID. When specifying an inventory item, you must always specify both inventoryReferenceId and inventoryReferenceType. | - **INVENTORY_ITEM**: This enum value is used if you want to identify a single-item listing by its item ID or SKU. - **INVENTORY_ITEM_GROUP**: This enum value is used if you want to identify a multi-variation listing by its item ID or inventoryItemGroupKey as defined in the Inventory API.",
"enum": [
"INVENTORY_ITEM",
"INVENTORY_ITEM_GROUP"
]
},
"ItemBasis": {
"type": "object",
"required": [
"estimatedValue",
"metric"
],
"properties": {
"estimatedValue": {
"type": "integer",
"description": "The estimated value of the search impressions for items based on the provided dimensions.
Duration: 17 days
Total slots: 200
Channel: Dweb, Mweb, Native",
"format": "int32"
},
"metric": {
"description": "The basis of the statistics.",
"$ref": "#/components/schemas/TargetingMetricsEnum"
}
},
"description": "This type defines the details regarding the basis for an item."
},
"ItemMarkdownStatus": {
"type": "object",
"properties": {
"listingMarkdownStatus": {
"description": "Indicates the state assigned to the markdown discount using one of the status values.",
"$ref": "#/components/schemas/ItemMarkdownStatusEnum"
},
"statusChangedDate": {
"type": "string",
"description": "Identifies the date the last time the state of the discount changed. Both both markdown and markup events can trigger a status change."
},
"statusMessage": {
"type": "string",
"description": "An eBay-assigned text string that describes the status of the discount."
}
},
"description": "This type defines the status of a markdown discount."
},
"ItemMarkdownStatusEnum": {
"description": "This enumerated type defines the item markdown status of a discount. | - **PENDING**: Indicates the system is still processing the item price markdown discount request. - **MARKED_DOWN**: Indicates item price markdown discount request succeeded and the discount has been scheduled. - **MARKED_UP**: Indicates the item is no longer in the markdown discount and the price has been \"marked up\" to its standard price. - **SKIPPED**: Indicates item price markdown discount has been skipped. - **FAILED**: Indicates item price markdown discount request failed. Check the configuration of your discount and resubmit the request.",
"type": "object",
"enum": [
"PENDING",
"MARKED_DOWN",
"MARKED_UP",
"SKIPPED",
"FAILED"
]
},
"ItemPriceMarkdown": {
"type": "object",
"required": [
"description",
"endDate",
"marketplaceId",
"name",
"promotionStatus",
"selectedInventoryDiscounts",
"startDate"
],
"properties": {
"applyFreeShipping": {
"type": "boolean",
"description": "If set to true, free shipping is applied to the first shipping service specified for the item. The first domestic shipping option is set to \"free shipping,\" regardless if the shipping optionType for that service is set to FLAT_RATE, CALCULATED, or NOT_SPECIFIED (freight). This flag essentially adds free shipping as a part of the discount.
Default: false"
},
"autoSelectFutureInventory": {
"type": "boolean",
"description": "If set to true, eBay will automatically add inventory items to the markdown discount if they meet the selectedInventoryDiscounts criteria specified for the markdown discount.
Default: false"
},
"blockPriceIncreaseInItemRevision": {
"type": "boolean",
"description": "If set to true, price increases (including removing the free shipping flag) are blocked and an error message is returned if a seller attempts to adjust the price of an item that's partaking in this markdown discount. If set to false, an item is dropped from the markdown discount if the seller adjusts the price.
Default: false"
},
"description": {
"type": "string",
"description": "This field is required if you are configuring an MARKDOWN_SALE discount.
This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" A tag line appears under the \"offer-type text\" that is generated for the discount. The text is displayed on the offer tile that is shown on the seller's All Offers page and on the event page for the discount. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"20% off\".
Maximum length: 50"
},
"endDate": {
"type": "string",
"description": "The date and time the discount ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). The value supplied for endDate must be at least 24 hours after the value supplied for the startDate of the markdown discount.
For display purposes, convert this time into the local time of the seller.
Max value:14 days for the AT, CH, DE, ES, FR, IE, IT, and UK, marketplaces.45 days for all other marketplaces.
"
},
"marketplaceId": {
"description": "The eBay marketplace ID of the site where the markdown discount is hosted. Markdown discounts are supported on all eBay marketplaces.",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"name": {
"type": "string",
"description": "The seller-defined name or 'title' of the discount that the seller can use to identify a discount. This label is not displayed in end-user flows.
Maximum length: 90"
},
"priority": {
"description": "This field is ignored in markdown discounts.",
"$ref": "#/components/schemas/PromotionPriorityEnum"
},
"promotionImageUrl": {
"type": "string",
"description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, populate this field with a URL that points to an image to be used with the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
},
"promotionStatus": {
"description": "The current status of the discount. When creating a new discount, you must set this value to either DRAFT or SCHEDULED.
Note that you must set this value to SCHEDULED when you update a RUNNING discount.",
"$ref": "#/components/schemas/PromotionStatusEnum"
},
"selectedInventoryDiscounts": {
"type": "array",
"description": "A list that defines the sets of selected items for the markdown discount.",
"items": {
"$ref": "#/components/schemas/SelectedInventoryDiscount"
}
},
"startDate": {
"type": "string",
"description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
}
},
"description": "This type defines the fields used to describe an item price markdown discount."
},
"ItemPromotion": {
"type": "object",
"required": [
"discountRules",
"endDate",
"inventoryCriterion",
"marketplaceId",
"name",
"promotionStatus",
"startDate"
],
"properties": {
"applyDiscountToSingleItemOnly": {
"type": "boolean",
"description": "This flag is relevant only when promotionType is set to VOLUME_DISCOUNT. For details on volume pricing discounts, see Configuring volume pricing discounts.
If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item that is being discounted. Otherwise, the discount applies to multiple quantities of any the items being discounted. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the discount."
},
"budget": {
"description": "This sets the budget for the CODED_COUPON discount type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The budget value for an active or paused discount can not be decreased.
Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.
",
"$ref": "#/components/schemas/Amount"
},
"couponConfiguration": {
"description": "The configuration of a coded coupon discount.",
"$ref": "#/components/schemas/CouponConfiguration"
},
"description": {
"type": "string",
"description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\"
The tag line appears under the \"offer-type text\" that is generated for the discount and is displayed on the offer tile that's shown on the seller's All Offers page, and on the event page for the discount. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. The offer-type text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50
Required if you are configuring CODED_COUPON, ORDER_DISCOUNT, or MARKDOWN_SALE discounts (and not valid for VOLUME_DISCOUNT discounts)."
},
"discountRules": {
"type": "array",
"description": "This container defines a discount using the following two required fields: - discountBenefit – Defines a discount as either a monetary amount or a percentage that is subtracted from the sales price of an item, a set of items, or an order.
- discountSpecification – Defines a set of rules that determine when the discount is applied.
Note: For volume pricing, you must specify at least two and not more than four discountBenefit/discountSpecification pairs. In addition, you must define each set of rules with a ruleOrder value that corresponds with the order of volume discounts you present.
Tip: Refer to Specifying item discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of discounts.
",
"items": {
"$ref": "#/components/schemas/DiscountRule"
}
},
"endDate": {
"type": "string",
"description": "The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
},
"inventoryCriterion": {
"description": "A container that defines either the listing IDs or the selection rules that specify the items to be discounted. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory. Note: All listings in Discounts Manager discounts must support an electronic payment method.
",
"$ref": "#/components/schemas/InventoryCriterion"
},
"marketplaceId": {
"description": "The eBay marketplace ID of the site where the threshold discount is hosted. Threshold discounts are currently supported on a limited number of eBay marketplaces. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"name": {
"type": "string",
"description": "The seller-defined name or \"title\" of the discount that the seller can use to identify a discounts. This label is not displayed in end-user flows.
Maximum length: 90"
},
"priority": {
"description": "Applicable for only ORDER_DISCOUNT discounts, this field indicates the precedence of the discounts, which is used to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence.",
"$ref": "#/components/schemas/PromotionPriorityEnum"
},
"promotionImageUrl": {
"type": "string",
"description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, and not valid for VOLUME_DISCOUNT discounts.
Populate this field with a URL that points to an image to be used with the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
},
"promotionStatus": {
"description": "The current status of the discount. When creating a new discount, this value must be set to either DRAFT or SCHEDULED.
Note that you must set this value to SCHEDULED when you update a RUNNING discount.",
"$ref": "#/components/schemas/PromotionStatusEnum"
},
"promotionType": {
"description": "Use this field to specify the type of the discount you are creating. The supported types are:
CODED_COUPON – A coupon code discount set with createItemPromotion.MARKDOWN_SALE – A markdown discount set with createItemPriceMarkdownPromotion.ORDER_DISCOUNT – A threshold discount set with createItemPromotion.VOLUME_DISCOUNT – A volume pricing discount set with createItemPromotion.
See the Discounts Manager documentation for details.
Required if you are creating a volume pricing discount (VOLUME_DISCOUNT).
",
"$ref": "#/components/schemas/PromotionTypeEnum"
},
"startDate": {
"type": "string",
"description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
}
},
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields that describe a threshold discount and includes the discount, the items being discounted, and the rules that specify when the discount is applied."
},
"ItemPromotionResponse": {
"type": "object",
"required": [
"discountRules",
"endDate",
"inventoryCriterion",
"inventoryCriterion",
"marketplaceId",
"name",
"promotionId",
"promotionStatus",
"startDate"
],
"properties": {
"applyDiscountToSingleItemOnly": {
"type": "boolean",
"description": "If set to true, the discount is applied only when the buyer purchases multiple quantities of a single item being discounted. Otherwise, the discount applies to multiple quantities of any items being discounted. Different variations of a multi-variation item are considered to be the same item. Note that this flag is not relevant if the inventoryCriterion container identifies a single listing ID for the discount."
},
"budget": {
"description": "This sets the budget for the CODED_COUPON discount type. Supported values range from 100-1000000. Supported currency codes include USD, GBP, EUR, and AUD. Note: The budget value for an active or paused discount can not be decreased.
Note: The Currency Code for 'budget' must be the same as the Currency Code for 'maxDiscountAmount'.
",
"$ref": "#/components/schemas/Amount"
},
"couponConfiguration": {
"description": "The configuration of a coded coupon discount.",
"$ref": "#/components/schemas/CouponConfiguration"
},
"description": {
"type": "string",
"description": "Required for CODED_COUPON discounts, this is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" The tag line appears under the \"offer-type text\" that is generated for the discount and is displayed under the offer tile that is shown on the seller's All Offers page and on the event page for the discount. This tag line is not used with volume pricing discounts. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50"
},
"discountRules": {
"type": "array",
"description": "A list containing the discount benefits (discountRule) and the rules that define when the benefit is applied (discountSpecification).",
"items": {
"$ref": "#/components/schemas/DiscountRule"
}
},
"endDate": {
"type": "string",
"description": "The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
},
"inventoryCriterion": {
"description": "Returns either an array of listing IDs or the selection rules used to specify the items being discounted. Listing IDs can be either eBay listing IDs or an array of seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory.",
"$ref": "#/components/schemas/InventoryCriterion"
},
"marketplaceId": {
"description": "The eBay marketplace ID of the site where the threshold discount is hosted. Threshold discounts are currently supported on a limited number of eBay marketplaces. Valid values:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"name": {
"type": "string",
"description": "The seller-defined name or \"title\" of the discount that the seller can use to identify a discount. This label is not displayed in end-user flows.
Maximum length: 90"
},
"priority": {
"description": "Applicable for only ORDER_DISCOUNT discounts, this field indicates the precedence of the discount, which eBay uses to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence.",
"$ref": "#/components/schemas/PromotionPriorityEnum"
},
"promotionId": {
"type": "string",
"description": "A unique eBay-assigned ID for the discount that's generated when the discount is created."
},
"promotionImageUrl": {
"type": "string",
"description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discounts, and not applicable for VOLUME_DISCOUNT discounts, this field is a URL that points to an image for the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
},
"promotionStatus": {
"description": "The current status of the discount. When creating a new discount, this value must be set to either DRAFT or SCHEDULED.",
"$ref": "#/components/schemas/PromotionStatusEnum"
},
"promotionType": {
"description": "Indicates the type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT.",
"$ref": "#/components/schemas/PromotionTypeEnum"
},
"startDate": {
"type": "string",
"description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
}
},
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This complex type defines the fields returned for an item (threshold) discount."
},
"ItemSelectModeEnum": {
"type": "object",
"description": "This enum type determines whether listings featured in an email campaign are selected by the seller or by eBay. | - **AUTO**: Automatic mode. The system will select items automatically based on the specified criteria such as price range and selected category. - **MANUAL**: Manual mode. The user selects eligible items manually and populates itemIds with listing codes.",
"enum": [
"AUTO",
"MANUAL"
]
},
"ItemSortEnum": {
"type": "object",
"description": "This enumerated type specifies the sort rule for displaying listings included in the email campaign. The default sort rule used is NEWLY_LISTED. | - **ENDING_FIRST**: Display items by date ending, with listings ending soonest first. - **HIGHEST_PRICED**: Display items by price, from highest to lowest. - **LOWEST_PRICED**: Display items by price, from lowest to highest. - **NEWLY_LISTED**: Display items by date listed, from newest to oldest. ",
"enum": [
"ENDING_FIRST",
"HIGHEST_PRICED",
"LOWEST_PRICED",
"NEWLY_LISTED"
]
},
"ItemsPagedCollection": {
"type": "object",
"required": [
"href",
"limit",
"listings",
"offset",
"total"
],
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"listings": {
"type": "array",
"description": "An array of the listings associated with a discount.",
"items": {
"$ref": "#/components/schemas/ListingDetail"
}
},
"next": {
"type": "string",
"description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
},
"total": {
"type": "integer",
"description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
"format": "int32"
},
"warnings": {
"type": "array",
"description": "A list of warnings that were generated by the request. Warning do not stop processing, but should be checked to ensure that the response contains the correct information.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"description": "This type defines the fields for a paginated result set of discounts. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
},
"Keyword": {
"type": "object",
"required": [
"adGroupId",
"keywordStatus",
"keywordText",
"matchType"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "This field identifies the ad group that the keyword is associated with."
},
"bid": {
"description": "The bid associated with the keyword. This container will not be returned if the keyword does not have a defined bid value.",
"$ref": "#/components/schemas/Amount"
},
"keywordId": {
"type": "string",
"description": "The unique identifier of a keyword."
},
"keywordStatus": {
"description": "The status of the keyword.
Valid Values:ACTIVEPAUSEDARCHIVED
",
"$ref": "#/components/schemas/KeywordStatusEnum"
},
"keywordText": {
"type": "string",
"description": "The text of the keyword."
},
"matchType": {
"description": "A field that defines the match type for the keyword.
Valid Values:BROADEXACTPHRASE
",
"$ref": "#/components/schemas/MatchTypeEnum"
}
},
"description": "A type that contains the details for keywords that are associated with an ad group.
Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model."
},
"KeywordPagedCollectionResponse": {
"type": "object",
"required": [
"href",
"keywords",
"limit",
"offset",
"total"
],
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"keywords": {
"type": "array",
"description": "This array contains all of the keywords that match the request criteria. Keywords will be sorted by adGroupId, regardless of whether you searched for keywords across the entire campaign, or if you searched for keywords within one or specific ad groups.",
"items": {
"$ref": "#/components/schemas/Keyword"
}
},
"limit": {
"type": "integer",
"description": "The number of keywords returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.
Max length: 2048"
},
"total": {
"type": "integer",
"description": "The total number of keywords retrieved in the result set.
If no keywords are found, this field is returned with a value of 0.",
"format": "int32"
}
},
"description": "A type that defines the keywords of the paged collection."
},
"KeywordRequest": {
"type": "object",
"required": [
"keywordText",
"matchType"
],
"properties": {
"keywordText": {
"type": "string",
"description": "The text of the keyword. Keywords are not case sensitive and compound words can be used without additional encoding (for example, tennis ball).
You can use the getKeywords method to retrieve keyword values currently associated with the specified ad group.
Maximum number of characters: 100
Maximum number of words: 10 "
},
"matchType": {
"description": "A field that defines the match type for the keyword.
Valid Values:BROADEXACTPHRASE
",
"$ref": "#/components/schemas/MatchTypeEnum"
}
},
"description": "A type that defines the fields used by the keyword requests."
},
"KeywordResponse": {
"type": "object",
"required": [
"adGroupId"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "The identifier of the ad group that the keyword was added to."
},
"errors": {
"type": "array",
"description": "This container will be returned if there is an issue creating the corresponding keyword and/or adding that keyword to the corresponding ad group.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"href": {
"type": "string",
"description": "The getKeyword URI for the keyword, which is used to retrieve the keyword. This URI will be returned for each successfully created keyword."
},
"keywordId": {
"type": "string",
"description": "A unique eBay-assigned ID for a keyword that is generated for an ad group. This keyword ID will be generated for each successfully created keyword."
},
"keywordText": {
"type": "string",
"description": "The text of the keyword."
},
"matchType": {
"description": "A field that defines the match type for the keyword.
Valid Values:BROADEXACTPHRASE
",
"$ref": "#/components/schemas/MatchTypeEnum"
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code is returned for each keyword to indicate the success or failure of adding that keyword to the ad group.",
"format": "int32"
},
"warnings": {
"type": "array",
"description": "List of warnings associated with this operation",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"description": "A type that defines the response fields used by the Keyword method."
},
"KeywordStatusEnum": {
"type": "object",
"description": "An enumerated type that indicates the status of existing keywords. | - **ACTIVE**: This enum value indicates that the keyword is active. - **PAUSED**: This enum value indicates that the keyword is in the paused state. Keywords can be moved back to the active state from the paused state. - **ARCHIVED**: This enum value indicates that the keyword is in the archived state. Keywords cannot be moved back to active state from the archived state. The keyword must be recreated to become active.",
"enum": [
"ACTIVE",
"PAUSED",
"ARCHIVED"
]
},
"ListingDetail": {
"type": "object",
"required": [
"currentPrice",
"freeShipping",
"title"
],
"properties": {
"currentPrice": {
"description": "The container that returns the current price of the listing.",
"$ref": "#/components/schemas/Amount"
},
"freeShipping": {
"type": "boolean",
"description": "If set to true, the seller pays for the shipping (or that the item is marked for local pickup only) In this case, the listing does not have an associated shipping cost for the first listed domestic-shipping option (even if the first domestic-shipping option specifies a flat-rate or calculated shipping option). If false, the buyer is required to pay for a flat-rate or calculated cost shipping service."
},
"inventoryReferenceId": {
"type": "string",
"description": "The seller's inventory reference ID for a listing. Also known as the \"SKU\" or \"custom label,\" an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing."
},
"inventoryReferenceType": {
"type": "string",
"description": "Indicates the type of the inventoryReferenceId, which can be either a single-SKU or a multi-SKU listing (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).
Note: This value is not currently returned in the response."
},
"listingCategoryId": {
"type": "string",
"description": "The ID of the category that listing belongs to. The ID is a numeric and unique identifier for the category that is assigned by eBay."
},
"listingCondition": {
"type": "string",
"description": "An eBay-assigned value that indicates condition of the associated item. For more information, see Item condition ID and name values."
},
"listingConditionId": {
"type": "string",
"description": "The ID of the condition associated with the item. For more information, see Item condition ID and name values.
Note: This value is not currently returned in the response."
},
"listingId": {
"type": "string",
"description": "A unique eBay-assigned ID that is generated when the item is listed."
},
"listingPromotionStatuses": {
"type": "array",
"description": "A list of the status values assigned to the item and the date that each new status was assigned.",
"items": {
"$ref": "#/components/schemas/ItemMarkdownStatus"
}
},
"quantity": {
"type": "integer",
"description": "The number of items being sold in the listing.",
"format": "int32"
},
"storeCategoryId": {
"type": "string",
"description": "Store CategoryId (if any) that to which the listing belongs. This field is blank if there is no seller Store category ID."
},
"title": {
"type": "string",
"description": "The seller-defined title of the listing that a seller can use to identify the item. This label is not displayed in end-user flows."
}
},
"description": "This type defines the fields that describe a listing that is in a discount."
},
"MarketplaceIdEnum": {
"type": "string",
"description": "This enumerated type defines the unique IDs for each of the eBay marketplaces. | - **EBAY_AT**: This enumeration value indicates that the eBay Marketplace is the Austria site (ebay.at). - **EBAY_AU**: This enumeration value indicates that the eBay Marketplace is the Australia site (ebay.com.au). - **EBAY_BE**: This enumeration value indicates that the eBay marketplace is the Belgium (Dutch) site (www.ebay.be). - **EBAY_CA**: This enumeration value indicates that the eBay Marketplace is the Canada (English) site (ebay.ca). - **EBAY_CH**: This enumeration value indicates that the eBay Marketplace is the Switzerland site (ebay.ch). - **EBAY_CN**: Reserved for future use. - **EBAY_CZ**: Reserved for future use. - **EBAY_DE**: This enumeration value indicates that the eBay Marketplace is the Germany site (ebay.de). - **EBAY_DK**: Reserved for future use. - **EBAY_ES**: This enumeration value indicates that the eBay Marketplace is the Spain site (ebay.es). - **EBAY_FI**: Reserved for future use. - **EBAY_FR**: This enumeration value indicates that the eBay Marketplace is the France site (ebay.fr). - **EBAY_GB**: This enumeration value indicates that the eBay Marketplace is the UK site (ebay.co.uk). - **EBAY_GR**: Reserved for future use. - **EBAY_HK**: This enumeration value indicates that the eBay Marketplace is the Hong Kong site (ebay.com.hk). - **EBAY_HU**: Reserved for future use. - **EBAY_ID**: Reserved for future use. - **EBAY_IE**: This enumeration value indicates that the eBay Marketplace is the Ireland site (ebay.ie). - **EBAY_IL**: Reserved for future use. - **EBAY_IN**: This enumeration value indicates that the eBay Marketplace is the India site (ebay.in). Note: eBay India is no longer a functioning eBay marketplace. - **EBAY_IT**: This enumeration value indicates that the eBay Marketplace is the Italy site (ebay.it). - **EBAY_JP**: Reserved for future use. - **EBAY_MY**: This enumeration value indicates that the eBay Marketplace is the Malaysia site (ebay.com/my). - **EBAY_NL**: This enumeration value indicates that the eBay Marketplace is the Netherlands site (ebay.nl). - **EBAY_NO**: Reserved for future use. - **EBAY_NZ**: Reserved for future use. - **EBAY_PE**: Reserved for future use. - **EBAY_PH**: This enumeration value indicates that the eBay Marketplace is the Philippines site (ebay.ph). - **EBAY_PL**: This enumeration value indicates that the eBay Marketplace is the Poland site (ebay.pl). - **EBAY_PR**: Reserved for future use. - **EBAY_PT**: Reserved for future use. - **EBAY_RU**: Reserved for future use. - **EBAY_SE**: Reserved for future use. - **EBAY_SG**: This enumeration value indicates that the eBay Marketplace is the Singapore site (ebay.com/sg). - **EBAY_TH**: This enumeration value indicates that the eBay Marketplace is the Thailand site (export.ebay.co.th). - **EBAY_TW**: This enumeration value indicates that the eBay Marketplace is the Taiwan site (ebay.com/tw). - **EBAY_US**: This enumeration value indicates that the eBay Marketplace is the US site (ebay.com). - **EBAY_VN**: This enumeration value indicates that the eBay Marketplace is the Vietnam site (ebay.vn). - **EBAY_ZA**: Reserved for future use. - **EBAY_HALF_US**: This enumeration value is no longer applicable as the Half.com site no longer exists. - **EBAY_MOTORS_US**: Indicates the parent category for \"Auto Parts and Vehicles\" on the EBAY_US marketplace (https://www.ebay.com/motors).",
"enum": [
"EBAY_AT",
"EBAY_AU",
"EBAY_BE",
"EBAY_CA",
"EBAY_CH",
"EBAY_CN",
"EBAY_CZ",
"EBAY_DE",
"EBAY_DK",
"EBAY_ES",
"EBAY_FI",
"EBAY_FR",
"EBAY_GB",
"EBAY_GR",
"EBAY_HK",
"EBAY_HU",
"EBAY_ID",
"EBAY_IE",
"EBAY_IL",
"EBAY_IN",
"EBAY_IT",
"EBAY_JP",
"EBAY_MY",
"EBAY_NL",
"EBAY_NO",
"EBAY_NZ",
"EBAY_PE",
"EBAY_PH",
"EBAY_PL",
"EBAY_PR",
"EBAY_PT",
"EBAY_RU",
"EBAY_SE",
"EBAY_SG",
"EBAY_TH",
"EBAY_TW",
"EBAY_US",
"EBAY_VN",
"EBAY_ZA",
"EBAY_HALF_US",
"EBAY_MOTORS_US"
]
},
"MatchTypeEnum": {
"type": "object",
"description": "An enumerated type that indicates the accepted match type. | - **BROAD**: This enum value indicates that broad matches are accepted. - **EXACT**: This enum value indicates that only exact matches are accepted. - **PHRASE**: This enum value indicates that phrasal matches are accepted.",
"enum": [
"BROAD",
"EXACT",
"PHRASE"
]
},
"MaxCpc": {
"type": "object",
"description": "This type defines the max CPC amount for a campaign.",
"properties": {
"amount": {
"description": "The allocated maximum CPC amount for a smart targeting campaign.
Both the currency and amount must be specified when allocating the Max CPC.",
"$ref": "#/components/schemas/Amount"
}
}
},
"MetricEnum": {
"type": "object",
"description": "An enumerated type that indicates the metric used to provide additional information about suggested keywords.
Note: All metric data is compiled for the marketplace associated with the specified campaign ID. | - **ACTIVE_SELLER_COUNT**: This enum value indicates the approximate number of sellers who have bid on the suggested keyword. - **SEARCH_VOLUME**: This enum value indicates the search volume for the suggested keyword.",
"enum": [
"ACTIVE_SELLER_COUNT",
"SEARCH_VOLUME"
]
},
"MetricMetadata": {
"type": "object",
"required": [
"description",
"metricKey"
],
"properties": {
"dataType": {
"description": "The data type of the returned metric value.",
"$ref": "#/components/schemas/DataTypeEnum"
},
"metricKey": {
"type": "string",
"description": "The name of the metric."
}
},
"description": "This type defines the name and data type of a metric."
},
"NegativeKeyword": {
"type": "object",
"required": [
"negativeKeywordId",
"negativeKeywordMatchType",
"negativeKeywordStatus",
"negativeKeywordText"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "An ad group ID that is generated when an ad group is first created and associated with a campaign.
Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller."
},
"campaignId": {
"type": "string",
"description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
},
"negativeKeywordId": {
"type": "string",
"description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
},
"negativeKeywordMatchType": {
"description": "A field that defines the match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values:EXACTPHRASE
",
"$ref": "#/components/schemas/NegativeKeywordMatchTypeEnum"
},
"negativeKeywordStatus": {
"description": "A field that defines the status of the negative keyword.",
"$ref": "#/components/schemas/NegativeKeywordStatusEnum"
},
"negativeKeywordText": {
"type": "string",
"description": "The text for the negative keyword."
}
},
"description": "A type that defines the fields for a negative keyword."
},
"NegativeKeywordMatchTypeEnum": {
"type": "object",
"description": "An enumerated type that indicates the accepted match type for negative keywords. | - **EXACT**: This enum value indicates that only exact matches are accepted. - **PHRASE**: This enum value indicates that phrasal matches are accepted.",
"enum": [
"EXACT",
"PHRASE"
]
},
"NegativeKeywordPagedCollectionResponse": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"negativeKeywords": {
"type": "array",
"description": "A list of negative keywords returned in the paginated collection.",
"items": {
"$ref": "#/components/schemas/NegativeKeyword"
}
},
"next": {
"type": "string",
"description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.
Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
},
"total": {
"type": "integer",
"description": "The total number of result sets in the paginated collection.",
"format": "int32"
}
},
"description": "A type that defines the negative keywords, returned in a paged collection."
},
"NegativeKeywordResponse": {
"type": "object",
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique identifier for an ad group that is generated when an ad group is first created and associated with a campaign."
},
"campaignId": {
"type": "string",
"description": "A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created."
},
"errors": {
"type": "array",
"description": "This container will be returned if there is an issue creating the corresponding negative keyword.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"href": {
"type": "string",
"description": "The URI for the negative keyword, which is used to retrieve the negative keyword. This URI will be returned for each successfully created negative keyword."
},
"negativeKeywordId": {
"type": "string",
"description": "A unique eBay-assigned ID for a negative keyword. This negative keyword ID will be generated for each successfully created negative keyword."
},
"negativeKeywordMatchType": {
"description": "The match type for the negative keyword.
Note: Broad matching of negative keywords is not currently supported.
Valid Values:EXACTPHRASE
",
"$ref": "#/components/schemas/NegativeKeywordMatchTypeEnum"
},
"negativeKeywordText": {
"type": "string",
"description": "The text for the negative keyword."
},
"statusCode": {
"type": "integer",
"description": "The status of the request to create a negative keyword. This field indicates whether the process was successful or not.",
"format": "int32"
}
},
"description": "A type that defines the negative keyword response."
},
"NegativeKeywordStatusEnum": {
"type": "object",
"description": "An enumerated type that defines the status of a request to create a negative keyword. | - **ACTIVE**: This enum value indicates that the negative keyword is active. - **ARCHIVED**: This enum value indicates that the negative keyword is archived. Negative keywords with this status cannot be set to ACTIVE again.",
"enum": [
"ACTIVE",
"ARCHIVED"
]
},
"PriceRange": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Specifies the currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type."
},
"gte": {
"type": "number",
"description": "The listings selected will be greater than or equal to this value. The value entered must be given in number format, such as 20.00.
Either gte, lte, or both must contain a value if the seller wishes to use a price range."
},
"lte": {
"type": "number",
"description": "The listings selected will be less than or equal to this value. The value entered must be given in number format, such as 100.00.
Either gte, lte, or both must contain a value if the seller wishes to use a price range."
}
},
"description": "This type defines the price range for the listings in an email campaign."
},
"PromotionDetail": {
"type": "object",
"required": [
"couponCode",
"endDate",
"marketplaceId",
"name",
"promotionHref",
"promotionId",
"promotionImageUrl",
"promotionStatus",
"promotionType",
"startDate"
],
"properties": {
"couponCode": {
"type": "string",
"description": "A unique code that buyers can use during checkout to receive a discount. The code must be unique across eBay."
},
"description": {
"type": "string",
"description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\" Tag lines appear under the \"offer-type text\" that is generated for a discount and displayed under the offer tile that is shown on the seller's All Offers page and on the discount's event page. Note: Offer-type text is a teaser that's presented throughout the buyer's journey through the sales flow and is generated by eBay. This text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, \"Extra 20% off when you buy 3+\".
Maximum length: 50
Required if you are configuring ORDER_DISCOUNT or MARKDOWN_SALE discounts (and not valid for VOLUME_DISCOUNT discounts)."
},
"endDate": {
"type": "string",
"description": "The date and time the discount ends in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
},
"marketplaceId": {
"description": "The eBay marketplace ID of the site where the discount is hosted. Threshold discounts are supported on a select set of marketplaces while markdown discounts are supported on all eBay marketplaces. Valid values for threshold discounts are as follows:
EBAY_AU = AustraliaEBAY_DE = GermanyEBAY_ES = SpainEBAY_FR = FranceEBAY_GB = Great BritainEBAY_IT = ItalyEBAY_US = United States
",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"name": {
"type": "string",
"description": "The seller-defined name or \"title\" of the discount, such as \"Buy 1 Get 1\", that the seller can use to identify a discount. This label is not displayed in end-user flows.
Maximum length: 90"
},
"priority": {
"description": "Applicable for only ORDER_DISCOUNT discount, this field indicates the precedence of the discount, which is used to determine the position of a discount on the seller's All Offers page. If an item is associated with multiple discounts, the discount with the higher priority takes precedence.",
"$ref": "#/components/schemas/PromotionPriorityEnum"
},
"promotionHref": {
"type": "string",
"description": "The URI of the discount details."
},
"promotionId": {
"type": "string",
"description": "A unique eBay-assigned ID for the discount that's generated when the discount is created."
},
"promotionImageUrl": {
"type": "string",
"description": "Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT discount, and not applicable for VOLUME_DISCOUNT discounts, this field is a URL that points to an image for the discount. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size."
},
"promotionStatus": {
"description": "The current status of the discount. When creating a new discount, you must set this value to either DRAFT or SCHEDULED.",
"$ref": "#/components/schemas/PromotionStatusEnum"
},
"promotionType": {
"description": "Indicates type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT.",
"$ref": "#/components/schemas/PromotionTypeEnum"
},
"startDate": {
"type": "string",
"description": "The date and time the discount starts in UTC format (yyyy-MM-ddThh:mm:ssZ). For display purposes, convert this time into the local time of the seller."
}
},
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields that describe a discount. This includes all the information about a discount except for the listings that are a part of the discount."
},
"PromotionPriorityEnum": {
"type": "object",
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
An enum that defines the values that represent the priority level of a discount, which is used to assign the precedence of a discount on the seller's All Offers page. | - **PRIORITY_1**: Indicates the rule is ranked first in priority. - **PRIORITY_2**: Indicates the rule is ranked second in priority. - **PRIORITY_3**: Indicates the rule is ranked third in priority. - **PRIORITY_4**: Indicates the rule is ranked fourth in priority. - **INVALID**: This is for internal use only for when priority specified in the request is invalid.",
"enum": [
"PRIORITY_1",
"PRIORITY_2",
"PRIORITY_3",
"PRIORITY_4",
"INVALID"
]
},
"PromotionReportDetail": {
"type": "object",
"required": [
"averageItemDiscount",
"averageOrderDiscount",
"averageOrderRevenue",
"averageOrderRevenue",
"averageOrderSize",
"baseSale",
"itemsSoldQuantity",
"numberOfOrdersSold",
"promotionHref",
"promotionId",
"promotionSale",
"promotionType",
"totalDiscount",
"totalSale"
],
"properties": {
"averageItemDiscount": {
"description": "The average item discount is the average discount that has been applied to each item being discounted. This value is calculated as follows:
totalDiscount / itemsSoldQuantity = averageItemDiscount",
"$ref": "#/components/schemas/Amount"
},
"averageItemRevenue": {
"description": "The average item revenue is the average revenue that has been received for each item being discounted.. This value is calculated as follows:
totalSales / itemsSoldQuantity = averageItemRevenue",
"$ref": "#/components/schemas/Amount"
},
"averageOrderDiscount": {
"description": "The average order discount is the average discount that has been applied to each order that has an active discount. This value is calculated as follows:
totalDiscount / numberOfOrdersSold = averageOrderDiscount",
"$ref": "#/components/schemas/Amount"
},
"averageOrderRevenue": {
"description": "The average order revenue is the average revenue that has been received for each order that has an active discount. This value is calculated as follows:
totalSales / numberOfOrdersSold = averageOrderRevenue",
"$ref": "#/components/schemas/Amount"
},
"averageOrderSize": {
"type": "string",
"description": "The average order size is the average number of items that each order contained that have an active discount. This value is calculated as follows:
itemsSoldQuantity / numberOfOrdersSold = averageOrderSize "
},
"baseSale": {
"description": "This is the monetary amount of items purchased that have been discounted where the threshold wasn't met, so the discount was not applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchased only one pair of socks, so they pay the full price of $5. Here, your baseSale amount would be $5.",
"$ref": "#/components/schemas/Amount"
},
"itemsSoldQuantity": {
"type": "integer",
"description": "This is the quantity of items purchased in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your number of items sold (itemsSoldQuantity) would be 2 and you number of orders sold (numberOfOrdersSold) would be 1.",
"format": "int32"
},
"numberOfOrdersSold": {
"type": "integer",
"description": "This is the number of orders sold in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your numberOfOrdersSold would be 1 and your itemsSoldQuantity would be 2.",
"format": "int32"
},
"percentageSalesLift": {
"type": "string",
"description": "The percentage sales lift is the total dollar amount gained due to discounts. This value is calculated as follows:
promotionSale / totalSale = percentageSalesLift "
},
"promotionHref": {
"type": "string",
"description": "The URI of the discount report."
},
"promotionId": {
"type": "string",
"description": "A unique eBay-assigned ID for the discount that's generated when the discount is created."
},
"promotionReportId": {
"type": "string",
"description": "The unique eBay-assigned ID of the discount report that is generated when the report is created."
},
"promotionSale": {
"description": "This is the monetary amount of the items sold in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your promotionSale amount would be $7.50.",
"$ref": "#/components/schemas/Amount"
},
"promotionType": {
"description": "Indicates the type of the discount, either CODED_COUPON, MARKDOWN_SALE, ORDER_DISCOUNT, or VOLUME_DISCOUNT.",
"$ref": "#/components/schemas/PromotionTypeEnum"
},
"totalDiscount": {
"description": "This is the monetary discount amount applied to the sale of items in a threshold discount where the threshold has been met and the discount was applied.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your totalDiscount amount would be $2.50.",
"$ref": "#/components/schemas/Amount"
},
"totalSale": {
"description": "This is the total monetary sales amount of all items sold that were discounted.
For example, suppose you're running a \"Buy 1, get 1 at 50%\" discount on $5 socks. You make one sale where the buyer purchases only one pair of socks and they pay the full price of $5 (baseSale). You make a second sale where the buyer purchases two pairs of socks and they pay $7.50, for both pairs (promotionSale). Your totalSale would be $12.50. This value is calculated as follows:
baseSale + promotionSale = totalSale",
"$ref": "#/components/schemas/Amount"
}
},
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields in a discount-level report."
},
"PromotionSelectModeEnum": {
"type": "object",
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This enumerated type is used to indicate how a discount is selected, if one is added to the email campaign. | - **AUTO**: Automatic mode. The system will select items automatically based on the specified criteria such as price range and selected category. - **MANUAL**: Manual mode. The user must selects the discount and adds it in the promotionId field. This mode can only be used if the user selects the listings included in itemIds.",
"enum": [
"AUTO",
"MANUAL"
]
},
"PromotionStatusEnum": {
"type": "object",
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
An enumerated type for the values that represent the different states that can be assigned to a discount. | - **SCHEDULED**: Indicates the discount start date is in future (greater than current date). The discount is not yet live. - **RUNNING**: Indicates the discount is live on the site. - **PAUSED**: Indicates the discount is currently on hold. Call resumePromotion to restart the discount. - **DRAFT**: Indicates the discount is a draft. Call updateItemPromotion to submit the full details of the discount, schedule it, and make it active. - **ENDED**: Indicates the discount has ended. - **INVALID**: This is for internal use only for when discount type specified in the request is invalid. ",
"enum": [
"SCHEDULED",
"RUNNING",
"PAUSED",
"DRAFT",
"ENDED",
"INVALID"
]
},
"PromotionTypeEnum": {
"type": "object",
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
An enum that defines the types of supported Discounts Manager discounts.
See the Discounts Manager documentation for details. | - **CODED_COUPON**: Discount type for coupon code discount set with createItemPromotion. - **MARKDOWN_SALE**: Discount type for markdown discount set with createItemPriceMarkdownPromotion. - **ORDER_DISCOUNT**: Discount type for threshold discount set with createItemPromotion. - **VOLUME_DISCOUNT**: Discount type for volume pricing discount set with createItemPromotion.",
"enum": [
"CODED_COUPON",
"MARKDOWN_SALE",
"ORDER_DISCOUNT",
"VOLUME_DISCOUNT"
]
},
"PromotionsPagedCollection": {
"type": "object",
"required": [
"href",
"limit",
"offset",
"promotions",
"total"
],
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
},
"promotions": {
"type": "array",
"description": "A list containing the details of each returned discount. This includes all the information about the discounts except for the listings that are discounted.",
"items": {
"$ref": "#/components/schemas/PromotionDetail"
}
},
"total": {
"type": "integer",
"description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
"format": "int32"
}
},
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields in a paginated result set of seller discounts. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
},
"PromotionsReportPagedCollection": {
"type": "object",
"required": [
"href",
"limit",
"offset",
"promotionReports",
"total"
],
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
},
"promotionReports": {
"type": "array",
"description": "A list of promotionReports contained in the paginated result set.",
"items": {
"$ref": "#/components/schemas/PromotionReportDetail"
}
},
"total": {
"type": "integer",
"description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
"format": "int32"
}
},
"description": "Note: As of July 8th 2024, promotions are now being referred to as discounts on Seller Hub and eBay help pages. Sell Marketing API documentation has been updated to reflect this product name change, but note that no API interface changes have been made.
This type defines the fields in a paginated result set of discount-level reports. The response consists of 0 or more sequenced pages that are returned from the complete result set, where each page consists of 0 or more items."
},
"ProposedBid": {
"type": "object",
"required": [
"currency",
"rangeEnd",
"rangeStart",
"value"
],
"properties": {
"currency": {
"description": "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.",
"$ref": "#/components/schemas/CurrencyCodeEnum"
},
"rangeEnd": {
"type": "string",
"description": "The end of the range specified for the bid."
},
"rangeStart": {
"type": "string",
"description": "The start of the range specified for the bid."
},
"value": {
"type": "string",
"description": "The value of the proposed bid."
}
},
"description": "A type that defines the data for a payment amount, such as the sale price."
},
"ReportFormatEnum": {
"type": "object",
"description": "This enum defines the format of a report file. Currently, the only supported format is TSV_GZIP, which is a gzip file with tab separated values. | - **TSV_GZIP**: Indicates a gzip file with tab separated values.",
"enum": [
"TSV_GZIP"
]
},
"ReportMetadata": {
"type": "object",
"required": [
"dimensionMetadata",
"maxNumberOfDimensionsToRequest",
"metricMetadata",
"reportType"
],
"properties": {
"dimensionMetadata": {
"type": "array",
"description": "A list containing the metadata for the dimension used in the report.",
"items": {
"$ref": "#/components/schemas/DimensionMetadata"
}
},
"maxNumberOfDimensionsToRequest": {
"type": "integer",
"description": "The maximum number of dimensions that can be requested for the specified report type.",
"format": "int32"
},
"maxNumberOfMetricsToRequest": {
"type": "integer",
"description": "The maximum number of metrics that can be requested for the specified report type.",
"format": "int32"
},
"channel": {
"description": "This field indicates whether a COST_PER_CLICK report type is related to an ON_SITE or OFF_SITE Promoted Listings campaign. This field is not returned for COST_PER_SALE report types since COST_PER_SALE campaigns are only available ON_SITE.",
"$ref": "#/components/schemas/ChannelEnum"
},
"metricMetadata": {
"type": "array",
"description": "A list containing the metadata for the metrics in the report.",
"items": {
"$ref": "#/components/schemas/MetricMetadata"
}
},
"reportType": {
"description": "The report_type, as specified in the request to create the report task.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending.",
"$ref": "#/components/schemas/ReportTypeEnum"
}
},
"description": "This type defines the fields included in the report."
},
"ReportMetadatas": {
"type": "object",
"required": [
"reportMetadata"
],
"properties": {
"reportMetadata": {
"type": "array",
"description": "A list of the metadata for the associated report type.",
"items": {
"$ref": "#/components/schemas/ReportMetadata"
}
}
},
"description": "This type defines the metadata used by the all report types."
},
"ReportTask": {
"type": "object",
"required": [
"dateFrom",
"dateTo",
"dimensions",
"marketplaceId",
"metricKeys",
"reportExpirationDate",
"reportFormat",
"reportHref",
"reportId",
"reportName",
"reportTaskCompletionDate",
"reportTaskCreationDate",
"reportTaskExpectedCompletionDate",
"reportTaskId",
"reportTaskStatus",
"reportType"
],
"properties": {
"campaignIds": {
"type": "array",
"description": "A list of IDs for the campaigns that are included in the report. A campaign ID is a unique eBay-assigned identifier of the campaign that's generated when the campaign is created.
Call getCampaigns to return the current campaign IDs for a seller.",
"items": {
"type": "string"
}
},
"channels": {
"type": "array",
"description": "The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign.",
"items": {
"$ref": "#/components/schemas/ChannelEnum"
}
},
"dateFrom": {
"type": "string",
"description": "The date defining the start of the timespan covered by the report, formatted as an ISO 8601 timestamp."
},
"dateTo": {
"type": "string",
"description": "The date defining the end of the timespan covered by the report, formatted as an ISO 8601 timestamp."
},
"dimensions": {
"type": "array",
"description": "A list containing the dimension in the report.",
"items": {
"$ref": "#/components/schemas/Dimension"
}
},
"fundingModels": {
"type": "array",
"description": "The funding model for the campaign that shall be included in the report.
Note: The default funding model for Promoted Listings reports is COST_PER_SALE.
Valid Values:COST_PER_SALECOST_PER_CLICK
",
"items": {
"$ref": "#/components/schemas/FundingModelEnum"
}
},
"inventoryReferences": {
"type": "array",
"description": "If supplied in the request, this field returns a list of the seller's inventory reference IDs included in the report. Each item is referenced by a pair of inventoryRefernceID and inventoryReferenceType values, where an inventory reference ID can be either a seller-defined SKU value or an inventoryItemGroupKey. An inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing), and is created and used by the Inventory API.
",
"items": {
"$ref": "#/components/schemas/InventoryReference"
}
},
"listingIds": {
"type": "array",
"description": "If supplied in the request, this field returns a list of the listing IDs included in the report. A listing ID is an eBay-assigned ID that's generated when a listing is created.",
"items": {
"type": "string"
}
},
"marketplaceId": {
"description": "The ID of the eBay marketplace used by the report task.",
"$ref": "#/components/schemas/MarketplaceIdEnum"
},
"metricKeys": {
"type": "array",
"description": "A list of metrics for the report task.",
"items": {
"type": "string"
}
},
"reportExpirationDate": {
"type": "string",
"description": "The date after which the report is no longer be available. Reports are available for 30 days and you cannot download a report after it has expired.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
},
"reportFormat": {
"description": "Indicates the format of the report. Currently, only TSV_GZIP is supported.",
"$ref": "#/components/schemas/ReportFormatEnum"
},
"reportHref": {
"type": "string",
"description": "The URL of the generated report, which can be used to download the report once it has been generated."
},
"reportId": {
"type": "string",
"description": "A unique eBay-assigned ID for the report."
},
"reportName": {
"type": "string",
"description": "An eBay-assigned name for the report that's created by the createReportTask call. This name is unique for the seller."
},
"reportTaskCompletionDate": {
"type": "string",
"description": "The date the report task completed the report generation.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
},
"reportTaskCreationDate": {
"type": "string",
"description": "The date the report task was created.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
},
"reportTaskExpectedCompletionDate": {
"type": "string",
"description": "The date the report task is expected to complete the report generation.
Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ"
},
"reportTaskId": {
"type": "string",
"description": "The unique eBay-assigned ID of the report task. This value is generated when the report task is created with a call to createReportTask."
},
"reportTaskStatus": {
"description": "Indicates the current state of the report task.",
"$ref": "#/components/schemas/TaskStatusEnum"
},
"reportTaskStatusMessage": {
"type": "string",
"description": "A status message with additional information about the report task."
},
"reportType": {
"description": "Indicates type of report associated with the report task.
Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending.",
"$ref": "#/components/schemas/ReportTypeEnum"
}
},
"description": "This type defines the fields in a report task."
},
"ReportTaskPagedCollection": {
"type": "object",
"required": [
"reportTasks"
],
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.
Max length: 2048"
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.
Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.
Max length: 2048"
},
"total": {
"type": "integer",
"description": "The total number of items retrieved in the result set.
If no items are found, this field is returned with a value of 0.",
"format": "int32"
},
"reportTasks": {
"type": "array",
"description": "A list of report tasks contained on this page from the paginated response.",
"items": {
"$ref": "#/components/schemas/ReportTask"
}
}
},
"description": "This type defines the fields that paginate the reports tasks returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set."
},
"ReportTypeEnum": {
"type": "object",
"description": "An enum that defines the type of reports you can generate.
Tip: For details about which report types can be used for Promoted Listings general strategy ad campaigns or Promoted Listings priority strategy ad campaigns, see Promoted Listings reporting. | - **ACCOUNT_PERFORMANCE_REPORT**: This enum value indicates that the report is based on the account performance. This report offers a daily view of the seller's Promoted Listings performance. - **ALL_CAMPAIGN_PERFORMANCE_SUMMARY_REPORT**: This enum value indicates that the report is based on campaign performance. This report provides performance data for all of a seller's campaigns. - **CAMPAIGN_PERFORMANCE_REPORT**: This enum value indicates that the report is a detailed item-based campaign performance report. This report offers an item level view of the performance of specific ad campaigns. - **CAMPAIGN_PERFORMANCE_SUMMARY_REPORT**: This enum value indicates that the report is a summary campaign performance report. This report offers a daily summary view of the performance of specific ad campaigns. - **INVENTORY_PERFORMANCE_REPORT**: This enum value indicates that the report is an inventory performance report. This report offers a listing view of the performance of all the seller's Promoted Listings.
Note: The Inventory Performance Summary report is not currently available; availability date is pending. - **LISTING_PERFORMANCE_REPORT**: This enum value indicates that the report is based on listings. This report offers a daily view of the performance of each listing. - **KEYWORD_PERFORMANCE_REPORT**: This enum value indicates that the report is a keyword performance report. This report provides keyword performance data for a specific campaign. - **TRANSACTION_REPORT**: This enum value indicates that the report is a transaction report. This report provides transaction-level details to sellers for both general strategy ad campaigns or priority strategy ad campaigns. - **SEARCH_QUERY_PERFORMANCE_REPORT**: This enum value indicates that the report is a search query performance report. This report offers details to sellers that help them understand buyer search patterns and behaviors, indicating which search queries most effectively led the buyers to their products and the impressions, clicks or amount of sales generated. This data can be used by sellers to choose more relevant keywords and negative keywords. ",
"enum": [
"ACCOUNT_PERFORMANCE_REPORT",
"ALL_CAMPAIGN_PERFORMANCE_SUMMARY_REPORT",
"CAMPAIGN_PERFORMANCE_REPORT",
"CAMPAIGN_PERFORMANCE_SUMMARY_REPORT",
"INVENTORY_PERFORMANCE_REPORT",
"LISTING_PERFORMANCE_REPORT",
"KEYWORD_PERFORMANCE_REPORT",
"TRANSACTION_REPORT",
"SEARCH_QUERY_PERFORMANCE_REPORT"
]
},
"RuleCriteria": {
"type": "object",
"properties": {
"excludeInventoryItems": {
"type": "array",
"description": "A list of seller inventory reference IDs to exclude from the discount.
Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters",
"items": {
"$ref": "#/components/schemas/InventoryItem"
}
},
"excludeListingIds": {
"type": "array",
"description": "A list of eBay listing IDs to exclude from the discount.
Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters",
"items": {
"type": "string"
}
},
"markupInventoryItems": {
"type": "array",
"description": "A list of SKUs to remove from a markdown discount. The listed SKUs are 'marked up' to their standard price after being part of the markdown discount.",
"items": {
"$ref": "#/components/schemas/InventoryItem"
}
},
"markupListingIds": {
"type": "array",
"description": "A list of listing IDs to remove from a markdown discount. The listed items are 'marked up' to their standard price after being part of the markdown discount.",
"items": {
"type": "string"
}
},
"selectionRules": {
"type": "array",
"description": "The container for the rules that select the items to be discounted.
Required if inventoryCriterionType is set to INVENTORY_BY_RULE.
For information on using the contained fields, see Item discounts.",
"items": {
"$ref": "#/components/schemas/SelectionRule"
}
}
},
"description": "This type defines the fields for a set of inventory selection rules.
Required: When inventoryCriterionType is set to INVENTORY_BY_RULE or INVENTORY_ANY."
},
"ScheduleDateTypeEnum": {
"type": "object",
"description": "This enumerated type specifies whether the user or the eBay system has set the schedule date for the email campaign. | - **SYSTEM**: The schedule date is determined by the system. - **CUSTOM**: The seller has set a custom send date for the email campaign.",
"enum": [
"SYSTEM",
"CUSTOM"
]
},
"SelectedInventoryDiscount": {
"type": "object",
"required": [
"discountBenefit",
"inventoryCriterion"
],
"properties": {
"discountBenefit": {
"description": "This container defines the discount as either a monetary amount or a percentage applied to the sales price.",
"$ref": "#/components/schemas/DiscountBenefit"
},
"discountId": {
"type": "string",
"description": "A unique, eBay-generated ID that you can use to identify the discount. This field is ignored in POST and PUT operations."
},
"inventoryCriterion": {
"description": "A container that defines either the listing IDs or the selection rules that specify the items to include in the discount. Listing IDs can be either eBay listing IDs or a list of the seller's inventory reference IDs (know as SKUs or custom labels). See the selectionRules container for the rule criteria you can use to select inventory. Note: All listings in Discounts Manager discounts must support an electronic payment method.
",
"$ref": "#/components/schemas/InventoryCriterion"
},
"ruleOrder": {
"type": "integer",
"description": "For markdown discounts, this field is reserved for future use. ",
"format": "int32"
}
},
"description": "This type defines the fields that describe the discounts applied to a set of inventory items and the order in which the selection rules are applied."
},
"SelectionRule": {
"type": "object",
"properties": {
"brands": {
"type": "array",
"description": "An array of product brands. For more details, see Using the selectionRules container.",
"items": {
"type": "string"
}
},
"categoryIds": {
"type": "array",
"description": "This field contains an array of the associated category ID(s).
For Item discounts, a single-item array containing the category ID associated with the discounts. Required when used in an Item discount and either specifying a selectionRules container or when inventoryCriterionType is set to INVENTORY_BY_RULE.
For Promoted Listing campaigns, an array of category ID(s) associated with the campaign.
For information on how to get category IDs, see eBay Marketplace category IDs and Seller store category IDs",
"items": {
"type": "string"
}
},
"categoryScope": {
"description": "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.
For Promoted Listing campaigns, this field includes the type of the category ID for the item(s) to be included in the campaign.
For Item discounts, this field identifies the scope for the corresponding array as eBay categories or for a seller's eBay store categories. Required when used in an Item discount and inventoryCriterionType is set to INVENTORY_BY_RULE. ",
"$ref": "#/components/schemas/CategoryScopeEnum"
},
"listingConditionIds": {
"type": "array",
"description": "A comma-separated list of unique identifiers for the conditions of listings to be included
For Promoted Listing campaigns, refer to Add items to the campaign. Up to four IDs can be specified.
For Item discounts, refer to Item condition ID and name values.",
"items": {
"type": "string"
}
},
"maxPrice": {
"description": "This container sets the maximum price threshold. For more details, see Using the selectionRules container.",
"$ref": "#/components/schemas/Amount"
},
"minPrice": {
"description": "This container sets the minimum price threshold. For more details, see Using the selectionRules container.",
"$ref": "#/components/schemas/Amount"
}
},
"description": "This type defines all rules/inclusion filters used to add listings to campaigns or discounts. Use of the specific fields is different for campaigns or discounts. See Using the selectionRules container."
},
"SortField": {
"type": "object",
"properties": {
"ascending": {
"type": "boolean",
"description": "If set to true, the results are sorted in ascending order. If set to false, the fields are sorted in descending order."
},
"field": {
"type": "string",
"description": "Specifies the name of the field on which the result set is sorted."
}
},
"description": "This type defines how the fields in the result set are sorted."
},
"SuggestBudgetResponse": {
"type": "object",
"properties": {
"suggestedBudget": {
"type": "array",
"description": "The suggested allocated daily budget for an offsite campaign.",
"items": {
"$ref": "#/components/schemas/BudgetRecommendationResponse"
}
}
},
"description": "This type defines the fields used in the suggestBudget response."
},
"SuggestMaxCpcRequest": {
"type": "object",
"required": [
"listingIds",
"marketplaceId"
],
"properties": {
"listingIds": {
"type": "array",
"description": "A comma delimited array of listing Ids the seller plans to associate with the smart targeting campaign for which the maxCpc will be suggested.",
"items": {
"type": "string"
}
},
"marketplaceId": {
"description": "The unique identifier of the marketplace where the listings are hosted. See Marketplace ID values for supported values.",
"$ref": "#/components/schemas/MarketplaceIdEnum"
}
},
"description": "This type defines the fields used in the suggestMaxCpc request. To retrieve the suggested maxCpc value for a smart targeting campaign, a seller must specify the listings associated with the campaign, as well as the marketplace on which the campaign is hosted."
},
"SuggestMaxCpcResponse": {
"type": "object",
"properties": {
"amount": {
"description": "The suggested maxCpc amount for the smart targeting campaign.",
"$ref": "#/components/schemas/Amount"
},
"marketplaceId": {
"description": "The unique identifier of the marketplace where the listings are hosted.",
"$ref": "#/components/schemas/MarketplaceIdEnum"
}
},
"description": "This type defines the fields used in the suggestMaxCpc response."
},
"SuggestedBids": {
"type": "object",
"required": [
"keywordText",
"matchType"
],
"properties": {
"keywordText": {
"type": "string",
"description": "The text for the keyword."
},
"matchType": {
"description": "A field that defines the match type for the keyword.
Valid Values:BROADEXACTPHRASE
",
"$ref": "#/components/schemas/MatchTypeEnum"
},
"proposedBid": {
"description": "The suggested bid associated with the keyword. ",
"$ref": "#/components/schemas/ProposedBid"
}
},
"description": "This type defines the suggested bid rate for the keyword."
},
"SuggestedKeywords": {
"type": "object",
"required": [
"keywordText"
],
"properties": {
"additionalInfo": {
"type": "array",
"description": "A container for the additional information and compiled insight data for suggested keywords. ",
"items": {
"$ref": "#/components/schemas/AdditionalInfo"
}
},
"keywordText": {
"type": "string",
"description": "The text for the keyword."
},
"matchType": {
"description": "A field that defines the match type for the keyword.
Valid Values:BROADEXACTPHRASE
",
"$ref": "#/components/schemas/MatchTypeEnum"
}
},
"description": "This type defines the suggested keywords for the item."
},
"SummaryReportResponse": {
"type": "object",
"required": [
"baseSale",
"lastUpdated",
"percentageSalesLift",
"promotionSale",
"totalSale"
],
"properties": {
"baseSale": {
"description": "The total revenue from all the purchased items that were part of a discount but did not trigger a discount during the discount period.",
"$ref": "#/components/schemas/Amount"
},
"lastUpdated": {
"type": "string",
"description": "The date the report was generated."
},
"percentageSalesLift": {
"type": "string",
"description": "The percentage of the total dollar amount gained due to discounts. This value is calculated as follows:
precentageSalesLift = promotionSale / (baseSale + promotionSale)"
},
"promotionSale": {
"description": "The total revenue from all the purchased items that were part of a discount and their purchase did trigger a discount during the discount period.",
"$ref": "#/components/schemas/Amount"
},
"totalSale": {
"description": "Total dollar sales amount of all the seller's listings, current to the date the report was generated.",
"$ref": "#/components/schemas/Amount"
}
},
"description": "This type defines the fields in an Discounts Manager Summary report. Reports are formatted in JSON. For more details, see Reading item discount Summary reports."
},
"TargetedAdsPagedCollection": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The URI of the current page of results from the result set."
},
"limit": {
"type": "integer",
"description": "The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set."
},
"offset": {
"type": "integer",
"description": "The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Default: 0
Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results."
},
"suggestedItems": {
"type": "array",
"description": "A list of suggested items in the paginated collection.",
"items": {
"$ref": "#/components/schemas/TargetingItems"
}
},
"total": {
"type": "integer",
"description": "The total number of items retrieved in the result set.
Note: If no items are found, this field is returned with a value of 0.",
"format": "int32"
}
},
"description": "A type that defines the keywords of the paged collection."
},
"TargetedBidRequest": {
"type": "object",
"required": [
"keywords"
],
"properties": {
"keywords": {
"type": "array",
"description": "An array of keywords for which bids will be required.
Maximum number of keywords: 500",
"items": {
"$ref": "#/components/schemas/KeywordRequest"
}
}
},
"description": "A type that defines the targeted bid."
},
"TargetedBidsPagedCollection": {
"type": "object",
"properties": {
"suggestedBids": {
"type": "array",
"description": "A list of bids in the paginated collection.",
"items": {
"$ref": "#/components/schemas/SuggestedBids"
}
}
},
"description": "A type that defines the keywords of the paged collection."
},
"TargetedKeywordRequest": {
"required": [
"matchType"
],
"type": "object",
"properties": {
"additionalInfo": {
"type": "array",
"description": "A field used to indicate whether additional information and insight data shall be provided for suggested keywords.
Use this array to retrieve keyword insights, including active seller count and search volume.
Valid Value: KEYWORD_INSIGHTS",
"items": {
"$ref": "#/components/schemas/AdditionalInfoEnum"
}
},
"exclusions": {
"type": "array",
"description": "A field used to indicate that the keywords already selected by sellers for the specified listing IDs should be filtered out of the response, and only new and unique keyword recommendations shall be returned.
Valid Value: ADOPTED_KEYWORDS",
"items": {
"$ref": "#/components/schemas/ExclusionsEnum"
}
},
"listingIds": {
"type": "array",
"description": "A set of comma-separated listing IDs for the specific listings you wish to retrieve suggested keywords.
Maximum number of listings requested: 300",
"items": {
"type": "string"
}
},
"matchType": {
"description": "A field that defines the match type for the keyword.
Valid Values:BROADEXACTPHRASE
",
"$ref": "#/components/schemas/MatchTypeEnum"
}
},
"description": "A type that provides details for the targeted keywords."
},
"TargetedKeywordsPagedCollection": {
"type": "object",
"properties": {
"suggestedKeywords": {
"type": "array",
"description": "A list of suggested keywords in the paged collection. Note: A relevancy check with items already present in the ad-group is performed even if item IDs associated with the ad-group are not explicitly passed in the request.
",
"items": {
"$ref": "#/components/schemas/SuggestedKeywords"
}
}
},
"description": "A type that defines the keywords of the paged collection."
},
"TargetingItems": {
"type": "object",
"required": [
"listingId"
],
"properties": {
"bases": {
"type": "array",
"description": "The metrics and additional information for the items.",
"items": {
"$ref": "#/components/schemas/ItemBasis"
}
},
"listingId": {
"type": "string",
"description": "The listing ID of the targeted item."
}
},
"description": "A type that defines the targeted items."
},
"TargetingMetricsEnum": {
"type": "object",
"description": "An enumerated type that indicates the basis for the targeted metrics. | - **SEARCH_IMPRESSIONS**: This enum value indicates that targeting metrics are based on search impressions in search slots.",
"enum": [
"SEARCH_IMPRESSIONS"
]
},
"TaskStatusEnum": {
"type": "object",
"description": "An enum that defines the possible states of a report task. | - **PENDING**: Indicates the report task is being worked upon. You cannot make changes to a task in this state. - **SUCCESS**: Indicates the report task ran successfully. - **FAILED**: Indicates the report task failed to run.",
"enum": [
"PENDING",
"SUCCESS",
"FAILED"
]
},
"UpdateAdGroupRequest": {
"type": "object",
"properties": {
"adGroupStatus": {
"description": "An enumeration value representing the current status of the ad group.If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again.
Valid Values:
ACTIVEPAUSEDARCHIVED
",
"$ref": "#/components/schemas/AdGroupStatusEnum"
},
"defaultBid": {
"description": "A bid amount that applies to all of the keywords in an ad group that do not have individual bids.",
"$ref": "#/components/schemas/Amount"
},
"name": {
"type": "string",
"description": "The updated name for the specified ad group."
}
},
"description": "A type that contains the fields used by the UpdateAdGroup request."
},
"UpdateAdStatusByListingIdRequest": {
"type": "object",
"required": [
"adStatus",
"listingId"
],
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.
Use the getAdGroups method to retrieve the ad group IDs for a seller."
},
"adStatus": {
"description": "An enumeration value representing the current status of the ad.
Valid Values:ACTIVEPAUSEDARCHIVED
",
"$ref": "#/components/schemas/AdStatusEnum"
},
"listingId": {
"type": "string",
"description": "A unique eBay-assigned identifier for a listing that is generated when the listing is created.
Note: This field accepts both listing IDs (as generated by the Inventory API), and item IDs (as used in the eBay Traditional API set, such as the Trading and Finding APIs)."
}
},
"description": "A type that contains the fields for the UpdateAdStatusByListingId request."
},
"UpdateAdStatusRequest": {
"type": "object",
"required": [
"adId",
"adStatus"
],
"properties": {
"adId": {
"type": "string",
"description": "A unique eBay-assigned identifier for an ad that belongs to the specified campaign.
Use the getAds method to retrieve ad IDs."
},
"adStatus": {
"description": "An enumeration value representing the status you wish to update the specified ad to.
Valid Values:ACTIVEPAUSEDARCHIVED
",
"$ref": "#/components/schemas/AdStatusEnum"
}
},
"description": "A type that contains the fields for the UpdateAdStatus request."
},
"UpdateAdrateStrategyRequest": {
"type": "object",
"properties": {
"adRateStrategy": {
"description": "This field is used to change the current ad rate strategy for a Cost Per Sale (CPS) campaign. It is not needed if the ad rate strategy is not being changed for the campaign.
Note: This field is not applicable for offsite campaigns.",
"$ref": "#/components/schemas/AdRateStrategyEnum"
},
"bidPercentage": {
"type": "string",
"description": "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 has a minimum value of 2.0 and a maximum value of 100.0."
},
"dynamicAdRatePreferences": {
"type": "array",
"description": "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",
"items": {
"$ref": "#/components/schemas/DynamicAdRatePreference"
}
}
},
"description": "A type that defines the request fields used to update the ad rate strategy for a Promoted Listings ad campaign."
},
"UpdateAdsByInventoryReferenceResponse": {
"type": "object",
"required": [
"statusCode"
],
"properties": {
"ads": {
"type": "array",
"description": "A list of ad IDs and links to retrieve them.",
"items": {
"$ref": "#/components/schemas/AdReference"
}
},
"errors": {
"type": "array",
"description": "A container for all of the errors associated with the specified inventory reference ID.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"inventoryReferenceId": {
"type": "string",
"description": "The reference ID associated with the ad. The reference ID could be a SKU number or Inventory Item Group, depending on value of inventoryReferenceType."
},
"inventoryReferenceType": {
"description": "The inventory reference type associated with the ad. The inventory reference type could be a SKU number or Inventory Item Group.",
"$ref": "#/components/schemas/InventoryReferenceTypeEnum"
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code that indicates whether or not the CPS ad was successfully updated.",
"format": "int32"
}
},
"description": "A type that contains the response fields used by the UpdateAdsByInventoryReference method."
},
"UpdateBidPercentageRequest": {
"type": "object",
"required": [
"bidPercentage"
],
"properties": {
"bidPercentage": {
"type": "string",
"description": "The updated bid percentage value for the specified ad in the specified campaign. The bid percentage (also known as the ad rate) is a user-defined value which 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.
Note: This field has a minimum value of 2.0 and a maximum value of 100.0."
}
},
"description": "This type specifies the bid percentage for an ad campaign."
},
"UpdateBiddingStrategyRequest": {
"type": "object",
"required": [
"biddingStrategy"
],
"properties": {
"biddingStrategy": {
"description": "The new bidding strategy for the specified Cost Per Click (CPC) campaign.",
"$ref": "#/components/schemas/BiddingStrategyEnum"
},
"bidPreferences": {
"type": "array",
"description": "This container indicates the bidding preferences of the campaign, such as the maximum CPC amount.
Note: This container is only applicable for smart targeting campaigns.
This container is required if the user wants to create a Smart Targeting campaign.",
"items": {
"$ref": "#/components/schemas/BidPreference"
}
}
},
"description": "This type defines the fields used in the updatedBiddingStrategy request."
},
"UpdateCampaignBudgetRequest": {
"type": "object",
"required": [
"daily"
],
"properties": {
"daily": {
"description": "The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign. 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.00100.00
",
"$ref": "#/components/schemas/BudgetRequest"
}
},
"description": "A type that contains the fields for the UpdateCampaignBudget request."
},
"UpdateCampaignIdentificationRequest": {
"type": "object",
"required": [
"campaignName",
"startDate"
],
"properties": {
"campaignName": {
"type": "string",
"description": "The new seller-defined name for the campaign. This value must be unique for the seller. If you don't want to change the name of the campaign, specify the current campaign name in this field.
You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters."
},
"endDate": {
"type": "string",
"description": "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.If you want to change only the end date of the campaign, you must specify the current campaign name, set the endDate as desired, and set the startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.
Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.
"
},
"startDate": {
"type": "string",
"description": "The new start date for the campaign, in UTC format (yyyy-MM-ddThh:mm:ssZ).If the campaign status is RUNNING or PAUSED, the startDate must be specified and must be the actual start date of the campaign, even if you are only changing the endDate. You can retrieve the campaign's startDate using the getCampaign method.
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 getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.
"
}
},
"description": "This type specifies the updated name, and start and end dates for an update-campaign request."
},
"UpdateCampaignRequest": {
"type": "object",
"required": [
"audienceCodes",
"itemSelectMode",
"personalizedMessage",
"subject"
],
"properties": {
"audienceCodes": {
"type": "array",
"description": "An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no limit to the number of audience codes that may be entered.
Example: if the current email campaign contains \"audienceCodes\": \"code1\", \"code2\" and the user wishes to add an audience code code3, set the audienceCodes value to \"audienceCodes\": \"code1\", \"code2\", \"code3\".
To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.",
"items": {
"type": "string"
}
},
"categoryId": {
"type": "string",
"description": "The unique identifier of either an eBay category or a store category.
This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.
Use the Taxonomy API to retrieve eBay categories. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.
itemSelectMode must be set to AUTO in order to use a category ID."
},
"categoryType": {
"description": "This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to.",
"$ref": "#/components/schemas/CategoryTypeEnum"
},
"itemIds": {
"type": "array",
"description": "An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them.
Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.
The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10.
itemSelectMode must be set to MANUAL in order to use this field.",
"items": {
"type": "string"
}
},
"itemSelectMode": {
"description": "Determines whether listings featured in an email campaign are selected by the seller or by eBay.
If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.
If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.
Note: itemSelectMode is always set to AUTO for WELCOME email campaigns.",
"$ref": "#/components/schemas/ItemSelectModeEnum"
},
"personalizedMessage": {
"type": "string",
"description": "The body of the email campaign. Accepts HTML and CSS. The maximum length is 1000 characters"
},
"priceRange": {
"description": "This container is used if the seller wants to apply the email campaign to listings based on a price range.
The priceRange container consists of the currency, gte, and lte fields.
\"gte\" stands for \"greater than or equal to\" and \"lte\" stands for \"less than or equal to\". Either gte, lte, or both must be used if the seller wishes to include a price range.
Note: Use this object when the itemSelectMode is set to AUTO.",
"$ref": "#/components/schemas/PriceRange"
},
"promotionId": {
"type": "string",
"description": "The ID of the discount used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT, and promotionSelectModeEnum is set to MANUAL.
To find a discount, call getPromotions to retrieve a list of the seller's discounts. Use the promotionId from an individual PromotionDetail result for the request."
},
"promotionSelectModeEnum": {
"description": "The selection mode for the discount used. If set to AUTO, eBay will choose the discount to include in the email campaign. If set to MANUAL, the seller must specify the discount in the promotionId field.
This field is required if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT.",
"$ref": "#/components/schemas/PromotionSelectModeEnum"
},
"scheduleDate": {
"type": "string",
"description": "The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z
This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated."
},
"sort": {
"description": "The sort rule is used to display the listings featured in the email campaign.
Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array.
The following sort rules are available:ENDING_FIRST displays listings by ending date, from soonest to latest.LOWEST_PRICED displays listings by price, from lowest to highest.HIGHEST_PRICED displays listings by price, from highest to lowest.NEWLY_LISTED displays listings by date listed, with the newest first.
The default sort rule is NEWLY_LISTED.",
"$ref": "#/components/schemas/ItemSortEnum"
},
"subject": {
"type": "string",
"description": "The email campaign subject. The maximum length is 70 characters."
}
},
"description": "This type defines the update email campaign request payload."
},
"UpdateEmailCampaignResponse": {
"type": "object",
"description": "This type defines the response payload for the updateEmailCampaign method.",
"required": [
"emailCampaignId",
"emailCampaignStatus"
],
"properties": {
"emailCampaignId": {
"type": "string",
"description": "The unique eBay-assigned ID to the email campaign that is generated when the email campaign is created."
},
"emailCampaignStatus": {
"description": "The email campaign status. See EmailCampaignStatusEnum for a list of email campaign statuses and their descriptions.",
"$ref": "#/components/schemas/EmailCampaignStatusEnum"
}
}
},
"UpdateKeywordByKeywordIdRequest": {
"type": "object",
"required": [
"keywordId"
],
"properties": {
"bid": {
"description": "This container is used to set or change the bid percentage for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the Cost Per Click (CPC) campaign.",
"$ref": "#/components/schemas/Amount"
},
"keywordId": {
"type": "string",
"description": "This field is used to identify the keyword to be updated. The getKeyword method can be used to retrieve keywordId values."
},
"keywordStatus": {
"description": "Include this field if you wish to change the status of the keyword. The status value specified here must be different than the keyword's current status. To confirm the current status of a keyword, you can use the getKeyword method.If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again.",
"$ref": "#/components/schemas/KeywordStatusEnum"
}
},
"description": "A type that contains the fields for the UpdateKeywordByKeywordId request."
},
"UpdateKeywordRequest": {
"type": "object",
"properties": {
"bid": {
"description": "This container is used to set or change the bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.",
"$ref": "#/components/schemas/Amount"
},
"keywordStatus": {
"description": "Include this field if you wish to change the status of the keyword. The status value specified here must be different than the keyword's current status. To confirm the current status of a keyword, you can use the getKeyword method.
If the status of the ad is currently ACTIVE, you can change status to PAUSED or ARCHIVED. If ad group is currently in PAUSED status, you can change the status back to ACTIVE. Ads that are currently in ARCHIVED status cannot be made ACTIVE again.",
"$ref": "#/components/schemas/KeywordStatusEnum"
}
},
"description": "A type that contains the fields for the UpdateKeyword request."
},
"UpdateKeywordResponse": {
"type": "object",
"required": [
"keywordId",
"statusCode"
],
"properties": {
"errors": {
"type": "array",
"description": "This container will be returned if there are one or more issues associated with modifying the corresponding keyword.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"keywordId": {
"type": "string",
"description": "This field identifies the keyword that the seller updated, or attempted to update."
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code is returned for each keyword to indicate the success or failure of updating that keyword.",
"format": "int32"
},
"warnings": {
"type": "array",
"description": "A list of warnings associated with this operation.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
}
},
"description": "A type that contains the fields for the UpdateKeyword response."
},
"UpdateNegativeKeywordIdRequest": {
"type": "object",
"required": [
"negativeKeywordId",
"negativeKeywordStatus"
],
"properties": {
"negativeKeywordId": {
"type": "string",
"description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword.
Use the getNegativeKeywords method to retrieve negative keyword IDs."
},
"negativeKeywordStatus": {
"description": "A field that defines the status of the negative keyword.
See NegativeKeywordStatusEnum for supported values.",
"$ref": "#/components/schemas/NegativeKeywordStatusEnum"
}
},
"description": "A type that defines the fields used to update a negative keyword."
},
"UpdateNegativeKeywordRequest": {
"type": "object",
"required": [
"negativeKeywordStatus"
],
"properties": {
"negativeKeywordStatus": {
"description": "A field that defines the status of the negative keyword.",
"$ref": "#/components/schemas/NegativeKeywordStatusEnum"
}
},
"description": "A type that contains the fields for the UpdateNegativeKeyword request."
},
"UpdateNegativeKeywordResponse": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"description": "A container that will be returned if there are one or more issues associated with modifying the corresponding negative keyword.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"negativeKeywordId": {
"type": "string",
"description": "A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword."
},
"statusCode": {
"type": "integer",
"description": "An HTTP status code that indicates the success or failure of updating that negative keyword.",
"format": "int32"
}
},
"description": "A type that contains the fields for the UpdateNegativeKeyword response."
},
"BulkUpsertVideoAdsPreferencesRequest": {
"type": "object",
"description": "This request type defines the listing-level video ads preference create or update operations to perform in a single request across multiple Promoted Listings ads within a CPC campaign.",
"properties": {
"requests": {
"type": "array",
"description": "An array of listing-level video ads preference updates. Include one object for each listing you want to create or update. You can specify up to 500 listing IDs in a single call, and the array must contain at least one item.
Maximum: 500 IDs per call",
"items": {
"$ref": "#/components/schemas/UpsertVideoAdsPreferencesRequest"
},
"minItems": 1
}
},
"required": [
"requests"
]
},
"BulkUpsertVideoAdsPreferencesResponse": {
"type": "object",
"description": "The base response container returned by the bulkUpsertVideoAdsPreferences operation. It contains the per-listing results for each attempted video ads preference update in the bulk request.",
"properties": {
"responses": {
"type": "array",
"description": "An array of per-listing results for the bulk request. Each element contains the outcome of the attempted video ads preference update for one listing.",
"items": {
"$ref": "#/components/schemas/UpsertVideoAdsPreferencesResponse"
}
}
}
},
"VideoAdsPreferences": {
"type": "object",
"description": "This request type defines the video ads preference settings to apply to a single listing in a Promoted Listings campaign that uses the CPC funding model. It is used as the videoAdsPreferences field value in both bulkUpsertVideoAdsPreferences and upsertVideoAdsPreferences.",
"properties": {
"videoAdsEnabled": {
"type": "boolean",
"description": "When true, video ads are enabled for the specified listing in the campaign, and any ads associated with that listing ID within the campaign are opted into video ads. When false, any ads associated with the specified listing ID within the campaign are opted out of video ads."
}
},
"required": [
"videoAdsEnabled"
]
},
"UpsertVideoAdsPreferencesRequest": {
"type": "object",
"description": "This request type defines the video ads preference create or update settings for a single listing in a campaign that uses the CPC funding model. It is used both for each listing item in the bulkUpsertVideoAdsPreferences request and as the request body for upsertVideoAdsPreferences.",
"properties": {
"listingId": {
"type": "string",
"description": "The unique eBay listing ID of the listing whose video ads preferences you want to create or update. This value is generated when a listing is created with the Trading API or the Inventory API."
},
"videoAdsPreferences": {
"$ref": "#/components/schemas/VideoAdsPreferences",
"description": "The video ads preference settings to apply to the specified listing in a campaign that uses the CPC funding model."
}
},
"required": [
"listingId",
"videoAdsPreferences"
]
},
"UpsertVideoAdsPreferencesResponse": {
"type": "object",
"description": "This response type contains the result of a video ads preference create or update operation for a single listing. It is returned as the response body for upsertVideoAdsPreferences and as the per-listing result type in bulkUpsertVideoAdsPreferences. It contains the outcome of the attempted video ads preference create or update operation for a single listing, including the listing ID, status code, and any errors associated with that listing.",
"properties": {
"errors": {
"type": "array",
"description": "A list of errors associated with the specified listing ID for the attempted video ads preference update. In a bulk response, this value applies to the individual listing result item.",
"items": {
"$ref": "#/components/schemas/ErrorDetailV3"
}
},
"listingId": {
"type": "string",
"description": "The unique eBay listing ID for the listing that was updated or attempted (this ID was generated when the listing was created)."
},
"statusCode": {
"type": "integer",
"format": "int32",
"description": "The HTTP status code returned for each listing that the seller attempted to update, whether for a single listing or for an individual listing within a bulk response."
}
}
}
},
"securitySchemes": {
"api_auth": {
"type": "oauth2",
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope": "View public data from eBay"
}
},
"authorizationCode": {
"authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope/sell.marketing.readonly": "View your eBay marketing activities, such as ad campaigns and listing promotions",
"https://api.ebay.com/oauth/api_scope/sell.marketing": "View and manage your eBay marketing activities, such as ad campaigns and listing promotions"
}
}
}
}
},
"responses": {
"Unauthorized": {
"description": "Unauthorized",
"x-response-codes": {
"errors": {
"1001": {
"domain": "API_MARKETING",
"category": "APPLICATION",
"description": "Invalid access token. Check the value of the Authorization HTTP request header."
}
}
}
}
}
}
}