{ "openapi": "3.0.0", "info": { "title": "Marketing API", "description": "
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://go.developer.ebay.com/api-license-agreement" }, "version": "v1.20.0" }, "servers": [ { "url": "https://api.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/sell/marketing/v1" } } } ], "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 Promoted Listings Standard (PLS) 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 Promoted Listings Advanced (PLA) campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, ads cannot be created.
For the ad group specified in the request, this method associates the ad with the specified ad group.
To create an ad for an ad group, specify the name of the ad group 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.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.
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" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPagedCollectionResponse" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "35013": { "domain": "API_MARKETING", "category": "REQUEST", "description": "The listing ID {listingId} is not valid." }, "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." }, "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}." }, "35083": { "domain": "API_MARKETING", "category": "REQUEST", "description": "The requested 'adStatus' is not valid." }, "36106": { "domain": "API_MARKETING", "category": "REQUEST", "description": "The 'ad_group_ids' is not supported for CPS funding model." } } } }, "404": { "description": "Not Found" }, "409": { "description": "Conflict", "x-response-codes": { "errors": { "35068": { "domain": "API_MARKETING", "category": "BUSINESS", "description": "You have exceeded the maximum number of listing IDs. Only {maxSupportedNumber} listings are supported per call." }, "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." } } } }, "500": { "description": "Internal Server 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." }, "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" ], "description": "This method adds a listing to an existing Promoted Listings campaign using a listingId value generated by the Trading API or Inventory API, or using a value generated by an ad group ID.For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.
For the listing ID specified in the request, this method:
To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.
For Promoted Listings Advanced (PLA) campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, an ad cannot be created.
For the ad group specified in the request, this method associates the ad with the specified ad group.
To create an ad for an ad group, specify the name of the ad group in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the 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."
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request",
"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 'adGroupId' {adGroupId} is not supported for CPS 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."
}
}
}
},
"404": {
"description": "Not Found"
},
"409": {
"description": "Business error",
"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",
"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.
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.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.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"
}
},
{
"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"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdGroupPagedCollectionResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"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"
},
"409": {
"description": "Business error"
},
"500": {
"description": "Internal Server 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."
},
"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": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.adGroupID
, which you can use to retrieve the ad group."
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request",
"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"
},
"409": {
"description": "Business error",
"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."
},
"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",
"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": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.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)A Promoted Listings campaign is the structure into which you place the ads or ad group for the listings you want to promote.
For Promoted Listings Standard and Promoted Listings Advanced campaigns, you can identify the items you want to place into a campaign either by \"key\" or by \"rule\" as follows:
true
so that after your campaign launches, eBay will regularly assess your new, revised, or newly-eligible listings to determine whether any should be added or removed from your campaign according to the rules you set. If there are, eBay will add or remove them automatically on a daily basis.Note: No matter how you add items to a Promoted Listings Standard or Promoted Listings Advanced campaign, each campaign can only contain ads for a maximum of 50,000 items.
If a rules-based campaign identifies more than 50,000 items, ads are created for only the first 50,000 items identified by the specified criteria, and ads are not created for the remaining items.
For Offsite Ads campaigns, sellers must set the channels array of the request body to OFF_SITE
. If no value is entered, the campaign will default to ON_SITE
. Only one Offsite Ads campaign can be created per seller.
Sellers can use the sugestBudget method to retrieve the suggested budget for an Offsite Ads campaign. If the budget is not provided for an Offsite Ads campaign, the suggested budget will be set as the budget.
Note: The Channels array is only applicable for campaigns that use the Cost Per click (CPC) funding model. Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine their eligibility status for eBay advertising programs.
Creating a campaign
To create a basic campaign, supply:
The campaign funding model specifies how the Promoted Listings fee is calculated. Currently, the supported funding models are COST_PER_SALE
and COST_PER_CLICK
. For complete information on how the fee is calculated and when it applies, see Promoted Listings fees.
If you populate the campaignCriterion object in your createCampaign request, campaign \"ads\" are created by \"rule\" for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign.
For details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see Promoted Listings campaign creation.
For recommendations on which listings are prime for a Promoted Listings ad campaign and to get guidance on how to set the bidPercentage field, see Using the Recommendation API to help configure campaigns.
Note: The Recommendation API is not applicable for Offsite Ads campaigns.
Tip: See Promoted Listings requirements and restrictions for the details on the marketplaces that support Promoted Listings via the API. See Promoted Listings restrictions for details about campaign limitations and restrictions.
", "operationId": "createCampaign", "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.campaignId
, which you can use to reference the campaign."
}
}
},
"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",
"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}."
},
"36101": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The daily budget value format is a maximum of two decimal points."
},
"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": "Business error",
"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."
},
"35132": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'biddingStrategy' field is not supported for CPS funding model."
},
"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",
"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.DRAFT
status. This changes the campaign status to RUNNING
or SCHEDULED
, based on its specified start date. Specify the campaign you wish to launch by supplying its campaign_id as a path parameter in the call URI. DRAFT
status. ",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"35021": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A campaign with the name of {campaignName} already exists. Please provide a different name."
},
"35043": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The campaign status of {campaignStatus} is either invalid or not supported for this operation."
},
"35045": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "No campaign found for campaign id {campaign_id}."
}
}
}
},
"409": {
"description": "Business error",
"x-response-codes": {
"errors": {
"35067": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The seller must accept the Promoted Listings terms and conditions. Please accept Promoted Listings terms and conditions by visiting this link {userAgreementLink} ."
}
}
}
},
"500": {
"description": "Internal Server 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."
},
"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}/pause": {
"post": {
"tags": [
"campaign"
],
"description": "This method pauses an active (RUNNING) campaign. 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"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"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"
},
"409": {
"description": "Business error",
"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."
}
}
}
},
"500": {
"description": "Internal Server 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."
},
"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.
FIXED
keyword bidding strategy which means that a seller manually assigns and adjusts keyword bids for their CPC campaign.DYNAMIC
bidding strategy which means that eBay will manage a campaign's keyword bids and automatically update them daily to the suggested bid.FIXED
and DYNAMIC
bidding strategies, refer to updateBiddingStrategy.DRAFT
status upon creation.campaignId
, which you can use to reference the campaign."
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"x-response-codes": {
"errors": {
"36362": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "Quick setup is unavailable for the {count} of the selected listings."
},
"36365": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The category is not supported by the Promoted Listing service for multi-quantity listings."
},
"36366": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The listing id was created on a different marketplace than the campaign. The listing and campaign must reside on the same marketplace."
},
"36367": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The listing id does not belong to the seller making this call."
},
"36368": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The listing id is not a fixed price item. This is a requirement for a promoted listing."
},
"36369": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing id is invalid or has ended."
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"35006": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "'fundingStrategy' is required for this call."
},
"35014": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing Id is required for this call."
},
"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."
},
"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."
},
"35037": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing associated with listing Id {listingId} has ended."
},
"35038": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The funding model is required. Valid values for 'fundingModel' are: {fundingModelValues}."
},
"35041": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'marketplaceId' is required."
},
"36160": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "This functionality is only supported for CPC funding model."
}
}
}
},
"409": {
"description": "Business error",
"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."
},
"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."
},
"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}."
},
"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}."
},
"36363": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "Quick setup is unavailable for the selected listings. Please check the listings and submit the call again."
}
}
}
},
"500": {
"description": "Internal Server 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."
},
"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/suggest_budget": {
"get": {
"tags": [
"campaign"
],
"description": "Note: This method is only supported for Offsite Ads campaigns. Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine if they are eligible for Offsite Ads.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.FIXED
DYNAMIC
FIXED
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"
}
},
{
"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"
}
}
],
"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"
},
"400": {
"description": "Bad Request",
"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"
},
"409": {
"description": "Business error",
"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."
},
"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",
"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": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.
This method adds keywords, in bulk, to an existing PLA ad group in a campaign that uses the Cost Per Click (CPC) funding model.
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" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordPagedCollectionResponse" } } } }, "400": { "description": "Bad Request", "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" }, "409": { "description": "Business error" }, "500": { "description": "Internal Server 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." }, "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": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.keywordId
, which you can use to reference the keyword."
}
}
},
"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",
"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"
},
"409": {
"description": "Business error",
"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."
},
"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",
"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": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.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"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NegativeKeywordPagedCollectionResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"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"
},
"404": {
"description": "Not Found"
},
"409": {
"description": "Business error",
"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."
}
}
}
},
"500": {
"description": "Internal Server 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.readonly",
"https://api.ebay.com/oauth/api_scope/sell.marketing"
]
}
]
},
"post": {
"tags": [
"negative_keyword"
],
"description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.negativeKeywordId
, which you can use to reference the negative keyword."
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"description": "Bad Request",
"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"
},
"409": {
"description": "Business error",
"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."
}
}
}
},
"500": {
"description": "Internal Server 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"
]
}
]
}
},
"/negative_keyword/{negative_keyword_id}": {
"get": {
"tags": [
"negative_keyword"
],
"description": "Note: This method is only available for select partners who have been approved for the eBay Promoted Listings Advanced (PLA) program. For information about how to request access to this program, refer to Promoted Listings Advanced Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for PLA, use the getAdvertisingEligibility method in Account API.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.
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 500,000 records; if this threshold is exceeded, the report will fail.
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 promotion, a markdown promotion does not require the buyer meet a \"threshold\" before the offer takes effect. With markdown promotions, all the buyer needs to do is purchase the item to receive the promotion benefit.
Important: There are some restrictions for which listings are available for price markdown promotions. For details, see Promotions Manager requirements and restrictions.
In addition, we recommend you list items at competitive prices before including them in your markdown promotions. For an extensive list of pricing recommendations, see the Growth tab in Seller Hub.
There are two ways to add items to markdown promotions:
New promotions must be created in either a DRAFT
or a SCHEDULED
state. Use the DRAFT state when you are initially creating a promotion and you want to be sure it's correctly configured before scheduling it to run. When you create a promotion, the promotion ID is returned in the Location response header. Use this ID to reference the promotion in subsequent requests (such as to schedule a promotion that's in a DRAFT state).
Tip: Refer to Promotions Manager in the Selling Integration Guide for details and examples showing how to create and manage seller promotions.
Markdown promotions are available on all eBay marketplaces. For more information, see Promotions 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.promotionId
, which you can use to reference the promotion."
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
},
"x-response-codes": {
"errors": {
"38226": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID must be numeric if you're using listingIds."
},
"38227": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The listing ID is invalid."
},
"38263": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The SKU or custom label used in inventoryReferenceId exceeds the maximum length, which is {skuLength}."
},
"38272": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This listing is not eligible for a promotion because it's an auction-style listing."
},
"38273": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This listing is not eligible for a promotion because it's a minimum advertised price (MAP) listing."
},
"38274": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "You haven't included electronic payment method as a payment method. In order to make this listing eligible, update it to include electronic payment method."
},
"38275": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "This SKU used in inventoryReferenceId matches an item that is part of a listing with variations. This SKU is only eligible if we add all of the listing variations. To add this listing, use the parent, or main, SKU (custom label)."
},
"345112": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Invalid Store category. Please refer to API documentation to source allowed values."
},
"345113": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Invalid marketplace category ID. Please refer to API documentation for the supported values."
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"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."
},
"38218": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A valid entry is required for {fieldName}."
},
"38219": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The start date and time must be earlier than the end date and time."
},
"38220": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The end date and time must be later than the current date and time."
},
"38228": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The amount value of '{fieldName}' contains decimals, only integers are supported."
},
"38229": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The start date and time should be later than the current date and time."
},
"38234": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "HTML is not allowed in the '{fieldName}' field."
},
"38235": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Invalid input for the '{fieldName}' field. For help, see the documentation for this call."
},
"38238": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The 'discountBenefit' data is missing, which is required by this call. For help, see the documentation for this call."
},
"38240": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Invalid input for the 'promotionStatus' field. For help, see the documentation for this call."
},
"38242": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The request can have only one of these fields: 'inventoryCriterion.inventoryItems' or 'inventoryCriterion.listingIds'."
},
"38255": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The promotion description exceeds the maximum length, which is {promoDescriptionLength}."
},
"38256": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The promotion name exceeds the maximum length, which is {promoNameLength}."
},
"38261": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Promotions are currently limited to a maximum of {maxListingInclLimit} parent items, when entering item IDs or choosing from live inventory."
},
"38262": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You can only include up to {maxSkuInclLimit} SKUs or custom labels in inventoryItems."
},
"38270": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The currency type does not match what is used for the Marketplace ID submitted."
},
"345056": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The request can have only one of these field types: 'inventoryItems' or 'listingIds'."
},
"345057": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The request can have only one of these fields: 'percentageOffItem', or 'amountOffItem' in 'discountBenefit'. For help, see the documentation for this call."
},
"345058": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "When using multiple selectedInventoryDiscounts containers, each must have a unique percentageoffitems value. For help, see the documentation for this call."
},
"345059": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "If using percentageoffitems you can have between 1 and 10 selectedInventoryDiscounts containers. For help, see the documentation for this call."
},
"345060": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "If using amountoffitems you can only have selectedInventoryDiscounts container. For help, see the documentation for this call."
},
"345061": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "The discount ID value is a read only value."
},
"345063": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Priority is not supported for the item_price_markdown calls."
},
"345110": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You can specify only one of Inventory Items, Listing IDs or Rules in the Inventory Criterion."
},
"345111": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot specify Rules when using the Inventory by Value Criterion."
},
"345114": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "A Category scope is required for the Rule. Please refer to API documentation for allowed values."
},
"345115": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "At least one Category is required. Please provide a valid input for this field and try again."
},
"345116": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You can specify only Marketplace categories or Store categories when creating Rules."
},
"345120": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "Invalid Item condition. Please refer to API documentation for allowed values."
},
"345121": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion."
},
"345122": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "category ids cannot be specified with the inventory of type any."
},
"345123": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "brands cannot be specified with inventory of type any or Store."
},
"345125": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot specify a child Marketplace Category ID when the parent Marketplace Category ID is already specified. Please refer to the API documentation to source allowed values."
},
"345126": {
"domain": "API_MARKETING",
"category": "REQUEST",
"description": "You cannot specify a child Store Category ID when the parent Store Category ID is already specified. Please refer to the API documentation to source allowed values."
}
}
}
},
"409": {
"description": "Business Error",
"x-response-codes": {
"errors": {
"38248": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'percentOffItem' value is invalid. For help, see the documentation for this call."
},
"38250": {
"domain": "API_MARKETING",
"category": "BUSINESS",
"description": "The 'amountOffItem' value is invalid. For help, see the documentation for this call."
}
}
}
},
"500": {
"description": "Internal Server 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"
]
}
]
}
},
"/item_price_markdown/{promotion_id}": {
"get": {
"tags": [
"item_price_markdown"
],
"description": "This method returns the complete details of the item price markdown promotion that's indicated by the promotion_id path parameter. 1********5@EBAY_US
",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemPriceMarkdown"
}
}
}
},
"400": {
"description": "Bad Request",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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"
]
}
]
},
"put": {
"tags": [
"item_price_markdown"
],
"description": "This method updates the specified item price markdown promotion with the new configuration that you supply in the payload of the request. Specify the promotion you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions. 1********5@EBAY_US
",
"required": true,
"schema": {
"type": "string"
}
},
{
"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"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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": "This method creates an item promotion, where the buyer receives a discount when they meet the buying criteria that's set for the promotion. Known here as \"threshold promotions\", these promotions trigger when a threshold is met. eBay highlights promoted items by placing teasers for the promoted 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 promotions 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 promotion:
You must create a new promotion in either a DRAFT
or SCHEDULED
state. Use the DRAFT state when you are initially creating a promotion and you want to be sure it's correctly configured before scheduling it to run. When you create a promotion, the promotion ID is returned in the Location response header. Use this ID to reference the promotion in subsequent requests.
Tip: Refer to the Selling Integration Guide for details and examples showing how to create and manage threshold promotions using the Promotions Manager.
For information on the eBay marketplaces that support item promotions, see Promotions 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"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemPromotionResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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": "This method updates the specified threshold promotion with the new configuration that you supply in the request. Indicate the promotion you want to update using the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.
When updating a promotion, supply all the fields that you used to configure the original promotion (and not just the fields you are updating). eBay replaces the specified promotion 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 promotion you're updating:
Tip: When updating a RUNNING
or PAUSED
promotion, set the status field to SCHEDULED
for the update request. When the promotion is updated, the previous status (either RUNNING
or PAUSED
) is retained.
1********5@EBAY_US
",
"required": true,
"schema": {
"type": "string"
}
},
{
"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"
}
}
],
"responses": {
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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": "This method returns the set of listings associated with the promotion_id specified in the path parameter. Call getPromotions to retrieve the IDs of a seller's promotions. 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" } }, { "name": "promotion_id", "in": "path", "description": "This path parameter takes a concatenation of the ID of the promotion associated with the listing set plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an \"at sign\" (@).1********5@EBAY_US
",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "Reserved for future use.",
"required": false,
"schema": {
"type": "string"
}
},
{
"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 promotions. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/sme:ItemMarkdownStatusEnum",
"required": false,
"schema": {
"type": "string"
}
}
],
"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",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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": {
"get": {
"tags": [
"promotion"
],
"description": "This method returns a list of a seller's undeleted promotions. The call returns up to 200 currently-available promotions on the specified marketplace. While the response body does not include the promotion's discountRules or inventoryCriterion containers, it does include the promotionHref (which you can use to retrieve the complete details of the promotion).
Use query parameters to sort and filter the results by the number of promotions to return, the promotion state or type, and the eBay marketplace. You can also supply keywords to limit the response to the promotions that contain that keywords in the title of the promotion.
Maximum returned: 200
", "operationId": "getPromotions", "parameters": [ { "name": "limit", "in": "query", "description": "Specifies the maximum number of promotions 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" } }, { "name": "promotion_status", "in": "query", "description": "This parameter specifies the promotion state by which you want to filter the results. The response contains only those promotions that match the state you specify.sort=END_DATE
Sorts the promotions in the response by their end dates in ascending order sort=-PROMOTION_NAME
Sorts the promotions by their promotion name in descending alphabetical order (Z-Az-a) START_DATE
END_DATE
PROMOTION_NAME
RUNNING
to PAUSED
. Pausing a promotion makes the promotion temporarily unavailable to buyers and any currently-incomplete transactions will not receive the promotional offer until the promotion is resumed. Also, promotion teasers are not displayed when a promotion is paused. 1********5@EBAY_US
",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Success"
},
"400": {
"description": "Bad Request",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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": "This method restarts a threshold promotion that was previously paused and changes the state of the promotion from PAUSED
to RUNNING
. Only promotions that have been previously paused can be resumed. Resuming a promotion reinstates the promotional teasers and any transactions that were in motion before the promotion was paused will again be eligible for the promotion. 1********5@EBAY_US
",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Success"
},
"400": {
"description": "Bad Request",
"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."
}
}
}
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server 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": "This method generates a report that lists the seller's running, paused, and ended promotions for the specified eBay marketplace. The result set can be filtered by the promotion status and the number of results to return. You can also supply keywords to limit the report to promotions that contain the specified keywords. 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" } }, { "name": "promotion_status", "in": "query", "description": "This parameter specifies the promotion state by which you want to filter the results.RUNNING
, PAUSED
, and ENDED
promotions (deleted reports are not returned) and summarizes the seller's campaign performance for all promotions 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"
}
},
{
"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"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetEmailCampaignsResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"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"
},
"500": {
"description": "Internal Server 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.768Z
ACTIVE
PAUSED
ARCHIVED
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": "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": { "type": "string", "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.
For implementation help, refer to eBay API documentation" }, "listingId": { "type": "string", "description": "A unique eBay-assigned ID that is generated when a listing is created." } }, "description": "A type that defines the fields for an ad." }, "AdGroup": { "type": "object", "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": { "type": "string", "description": "An enumeration value representing the current status of the ad group.ACTIVE
PAUSED
ARCHIVED
Default: 0
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 items retrieved in the result set.0
.",
"format": "int32"
}
},
"description": "A container for 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."
},
"AdReference": {
"type": "object",
"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",
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a Promoted Listings Advanced (PLA) 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/Error"
}
},
"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."
},
"AdUpdateResponse": {
"type": "object",
"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/Error"
}
},
"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",
"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/Error"
}
},
"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",
"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/Error"
}
},
"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": {
"type": "string",
"description": "The type of additional information provided for the suggested keyword.KEYWORD_INSIGHTS
For implementation help, refer to eBay API documentation"
},
"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": {
"type": "string",
"description": "The metric used to provide additional information for the suggested keyword.ACTIVE_SELLER_COUNT
SEARCH_VOLUME
MARKETPLACE_ID
, the value would be from MarketplaceIdEnum."
}
},
"description": "A type that contains the dimension fields."
},
"Amount": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "The base currency applied to the value field to establish a monetary amount. CAD
. MINIMUM_REQUIRED
. For implementation help, refer to eBay API documentation"
},
"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."
},
"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/Error"
}
}
},
"description": "This type defines the fields for any warning error messages."
},
"Budget": {
"type": "object",
"properties": {
"amount": {
"description": "The allocated budget amount for a CPC Promoted Listings campaign.",
"$ref": "#/components/schemas/Amount"
},
"budgetStatus": {
"type": "string",
"description": "The budget status for a CPC Promoted Listings campaign. For implementation help, refer to eBay API documentation"
}
},
"description": "A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.ON_SITE
OFF_SITE
You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.
Max length: 80 characters" }, "campaignStatus": { "type": "string", "description": "Indicates the status of the campaign, such asRUNNING
, PAUSED
, and ENDED
. For implementation help, refer to eBay API documentation"
},
"channels": {
"type": "array",
"description": "The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign. ON_SITE
OFF_SITE
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.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": {
"type": "string",
"description": "The ID of the eBay marketplace where the campaign is hosted. For implementation help, refer to eBay API documentation"
},
"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", "properties": { "audienceType": { "type": "string", "description": "This enum value indicates the audience type. For the complete list of audience types and their associated enum values, see AudienceTypeEnum. For implementation help, refer to eBay API documentation" }, "code": { "type": "string", "description": "The unique code for an audience. " }, "name": { "type": "string", "description": "The display name for an audience." } }, "description": "This is 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.00
100.00
true
, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory.false
"
},
"criterionType": {
"type": "string",
"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."
},
"Campaigns": {
"type": "object",
"properties": {
"campaigns": {
"type": "array",
"description": "This is an array of one or campaigns that match the listing or inventory item group specified in the request.",
"items": {
"$ref": "#/components/schemas/Campaign"
}
}
},
"description": "This type contains a list of campaigns."
},
"CloneCampaignRequest": {
"type": "object",
"properties": {
"campaignName": {
"type": "string",
"description": "A seller-defined name for the newly-cloned campaign. This value must be unique for the seller.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.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",
"properties": {
"adGroupId": {
"type": "string",
"description": "Note: This field is not currently in use. Ad groups are only applicable to Promoted Listings Advanced (PLA) 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": {
"type": "string",
"description": "This enumerated value indicates the type of item the inventoryReferenceId references.INVENTORY_ITEM
or an INVENTORY_ITEM_GROUP
. For implementation help, refer to eBay API documentation"
}
},
"description": "This type defines the fields needed to create ads by inventory reference ID request."
},
"CreateAdsByInventoryReferenceResponse": {
"type": "object",
"properties": {
"adGroupId": {
"type": "string",
"description": "A unique eBay-assigned ID for an ad group in a Promoted Listings Advanced (PLA) 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/Error"
}
},
"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": { "type": "string", "description": "Indicates the type of item the inventoryReferenceId references. The item can be either anINVENTORY_ITEM
or an INVENTORY_ITEM_GROUP
. For implementation help, refer to eBay API documentation"
},
"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",
"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" }, "channels": { "type": "array", "description": "The channel for the campaign. This value indicates whether the advertising campaign is an Onsite or Offsite.ON_SITE
. Multiple channels are not supported. ON_SITE
OFF_SITE
OFF_SITE
for an Offsite Ads campaign.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"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", "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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"emailCampaignType": {
"type": "string",
"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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"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 promotion used for an email campaign if the emailCampaignType is set to COUPON
, SALE_EVENT
, or ORDER_DISCOUNT
. promotionSelectModeEnum must set to MANUAL
if a promotion is selected.COUPON
, SALE_EVENT
, or ORDER_DISCOUNT
.AUTO
, eBay will choose the promotion to include in the email campaign. If set to MANUAL
, the seller must specify the promotion in the promotionId field. For implementation help, refer to eBay API documentation"
},
"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
. For implementation help, refer to eBay API documentation"
},
"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. For implementation help, refer to eBay API documentation"
}
}
},
"CreateKeywordRequest": {
"type": "object",
"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 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.BROAD
EXACT
PHRASE
EXACT
PHRASE
NON_PERFORMING_DATA
",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"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_SITE
OFF_SITE
OFF_SITE
if the report is for a Offsite Ads campaign.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"dateFrom": {
"type": "string",
"description": "The date defining the start of the timespan covered by the report.[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
2021-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]Z
2021-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_SALE
COST_PER_CLICK
INVENTORY_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": { "type": "string", "description": "The file format of the report. Currently, the only supported format isTSV_GZIP
, which is a gzip file with tab separated values. For implementation help, refer to eBay API documentation"
},
"reportType": {
"type": "string",
"description": "The type of report to be generated, such as ACCOUNT_PERFORMANCE_REPORT
or CAMPAIGN_PERFORMANCE_REPORT
.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", "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/Error" } }, "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", "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": {
"type": "string",
"description": "This enumerated value indicates the type of item the inventoryReferenceId references.INVENTORY_ITEM
or an INVENTORY_ITEM_GROUP
. For implementation help, refer to eBay API documentation"
}
},
"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",
"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/Error"
}
},
"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": {
"type": "string",
"description": "The enumeration value returned here indicates if the ad was for a single-variation listing or a multiple-variation listing. For implementation help, refer to eBay API documentation"
},
"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",
"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",
"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", "properties": { "annotationKey": { "type": "string", "description": "An annotation key associated with the dimension." }, "dataType": { "type": "string", "description": "The data type of the annotation key value. For implementation help, refer to eBay API documentation" } }, "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
."
},
"DimensionMetadata": {
"type": "object",
"properties": {
"dataType": {
"type": "string",
"description": "The data type of the dimension value used to create the report. For implementation help, refer to eBay API documentation"
},
"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 promotion 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
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 promoted item (or items) when the promotion criteria is met. 5
Max: 80
"
},
"percentageOffOrder": {
"type": "string",
"description": "Used for threshold promotions, this is the percentage of the order price that is discounted off the order when the promotion criteria is met. This field is not value for markdown promotions. 5
Max: 80
0
for the first discount rule."
}
},
"description": "This container defines the promotional 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:
Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification values to create different types of promotions.
" }, "DiscountRule": { "type": "object", "properties": { "discountBenefit": { "description": "This container defines the promotional discount as either a monetary amount or a percentage of the sales price.Note: When configuring promotion benefits, populate just one of the following fields in the discountBenefit container:
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 discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
", "$ref": "#/components/schemas/DiscountBenefit" }, "discountSpecification": { "description": "This container defines the criteria for when the discounts of a promotion trigger, such as the minimum quantity that the buyer must purchase before the promotion kicks in. The promotional 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:
Important: When configuring volume pricing promotions, 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 discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
", "$ref": "#/components/schemas/DiscountSpecification" }, "maxDiscountAmount": { "description": "The limit on how much a buyer can save using aCODED_COUPON
promotion 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.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 promotions, 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 promoted items before the promotional discount is applied.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. 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"
},
"minAmount": {
"description": "Known as the \"threshold amount\", the minimum dollar amount that needs to be spent on promoted items in order to qualify for the promotion's discount. 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 promoted items that needs to be bought in order to qualify for the promotion's discount. 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) promotions. 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
",
"format": "int32"
}
},
"description": "This container defines the criteria for when the discounts of a promotion trigger, such as the minimum quantity the buyer must purchase before the promotion kicks in. The promotional 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:
Tip: Refer to Configuring discounts for threshold promotions for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
" }, "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.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.inputRefId
.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "This optional complex field type contains a list of one or more context-specific ErrorParameter
objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter
object consists of two fields, a name
and a value
.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain."
}
},
"description": "A container that defines the elements of error and warning messages."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the entity that threw the error."
},
"value": {
"type": "string",
"description": "A description of the error."
}
},
"description": "Container for a error parameter."
},
"FundingStrategy": {
"type": "object",
"properties": {
"adRateStrategy": {
"type": "string",
"description": "This field is used to set the ad rate strategy for a Cost Per Sale (CPS) campaign.FIXED
. If this field is omitted, the default value will be used.FIXED
DYNAMIC
FIXED
bidding strategy.4.1
, 5.0
, 5.5
, ...0.01
, 10.75
, 99.99
,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.DYNAMIC
This field is not applicable for Offsite Ads campaigns.FIXED
",
"items": {
"$ref": "#/components/schemas/DynamicAdRatePreference"
}
},
"fundingModel": {
"type": "string",
"description": "Indicates the model that eBay uses to calculate the Promoted Listings fee. For a description of the funding model types, refer to FundingModelTypeEnum. For implementation help, refer to eBay API documentation"
}
},
"description": "This type defines how the Promoted Listings fee is calculated for a Promoted Listings ad campaign."
},
"GetEmailCampaignAudiencesResponse": {
"type": "object",
"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",
"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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"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": {
"type": "string",
"description": "The email campaign status. See EmailCampaignStatusEnum for a list of valid statuses. For implementation help, refer to eBay API documentation"
},
"emailCampaignType": {
"type": "string",
"description": "The email campaign type. See CampaignTypeEnum for valid email campaign types. For implementation help, refer to eBay API documentation"
},
"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": {
"type": "string",
"description": "The mode used to select the items listed in the email campaign. For implementation help, refer to eBay API documentation"
},
"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 promotion that was assigned to the email campaign."
},
"promotionSelectMode": {
"type": "string",
"description": "Indicates whether the listings that the promotion was applied to were selected manually or automatically.
This field will only return if a promotion was applied. For implementation help, refer to eBay API documentation"
},
"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": {
"type": "string",
"description": "The schedule type of the email campaign. See ScheduleDateTypeEnum. For implementation help, refer to eBay API documentation"
},
"sentDate": {
"type": "string",
"description": "The date and time that the email campaign was sent, given in UTC format."
},
"sort": {
"type": "string",
"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
. For implementation help, refer to eBay API documentation"
},
"subject": {
"type": "string",
"description": "The email campaign subject."
}
}
},
"GetEmailCampaignsResponse": {
"type": "object",
"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",
"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",
"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",
"properties": {
"inventoryCriterionType": {
"type": "string",
"description": "Indicates how the items to include in the promotion are selected. You can include inventory by ID, using rules, or globally include all your inventory. For implementation help, refer to eBay API documentation"
},
"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 promotion.
Note: The request can have either inventoryItems or listingIds, but not both.
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 added to the promotion. Note: The request can have either inventoryItems or listingIds, but not both.
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 promotion. 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 promotion. The \"listing IDs\" are are either the seller's item IDs or the eBay listing IDs."
},
"InventoryItem": {
"type": "object",
"properties": {
"inventoryReferenceId": {
"type": "string",
"description": "The unique identifier of a single-item listing or a multi-variation listing.INVENTORY_ITEM
and specify and 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."
}
},
"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.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.INVENTORY_ITEM
or INVENTORY_ITEM_GROUP
.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 promotional bonus. false
"
},
"autoSelectFutureInventory": {
"type": "boolean",
"description": "If set to true
, eBay will automatically add inventory items to the markdown promotion if they meet the selectedInventoryDiscounts criteria specified for the markdown promotion. 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 promotion. If set to false
, an item is dropped from the markdown promotion if the seller adjusts the price. false
"
},
"description": {
"type": "string",
"description": "This field is required if you are configuring an MARKDOWN_SALE promotion. 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\".
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 promotion.14
days for the AT, CH, DE, ES, FR, IE, IT, and UK, marketplaces.45
days for all other marketplaces.DRAFT
or SCHEDULED
. SCHEDULED
when you update a RUNNING promotion. For implementation help, refer to eBay API documentation"
},
"selectedInventoryDiscounts": {
"type": "array",
"description": "A list that defines the sets of selected items for the markdown promotion and the discount specified for promotion.",
"items": {
"$ref": "#/components/schemas/SelectedInventoryDiscount"
}
},
"startDate": {
"type": "string",
"description": "The date and time the promotion 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 promotion."
},
"ItemPromotion": {
"type": "object",
"properties": {
"applyDiscountToSingleItemOnly": {
"type": "boolean",
"description": "This flag is relevant in only when promotionType is set to VOLUME_DISCOUNT
. For details on volume pricing promotions, see Configuring volume pricing discounts. true
, the discount is applied only when the buyer purchases multiple quantities of a single item in the promotion. Otherwise, the promotional discount applies to multiple quantities of any items in the promotion. 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 promotion."
},
"budget": {
"description": "This sets the budget for the CODED_COUPON
promotion 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 promotion 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 promotion.", "$ref": "#/components/schemas/CouponConfiguration" }, "description": { "type": "string", "description": "This is the seller-defined \"tag line\" for the offer, such as \"Save on designer shoes.\"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+\".
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 promotion discounts for information and examples on how to combine discountBenefit and discountSpecification to create different types of promotions.
", "items": { "$ref": "#/components/schemas/DiscountRule" } }, "endDate": { "type": "string", "description": "The date and time the promotion 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 include in the promotion. 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 Promotions Manager promotions must support an electronic payment method.
", "$ref": "#/components/schemas/InventoryCriterion" }, "marketplaceId": { "type": "string", "description": "The eBay marketplace ID of the site where the threshold promotion is hosted. Threshold promotions 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 StatesDRAFT
or SCHEDULED
. SCHEDULED
when you update a RUNNING promotion. For implementation help, refer to eBay API documentation"
},
"promotionType": {
"type": "string",
"description": "Use this field to specify the type of the promotion you are creating. The supported types are:
CODED_COUPON
– A coupon code promotion set with createItemPromotion.MARKDOWN_SALE
– A markdown promotion set with createItemPriceMarkdownPromotion.ORDER_DISCOUNT
– A threshold promotion set with createItemPromotion.VOLUME_DISCOUNT
– A volume pricing promotion set with createItemPromotion.See the Promotions Manager documentation for details.
Required if you are creating a volume pricing promotion (VOLUME_DISCOUNT
).
yyyy-MM-ddThh:mm:ssZ
). For display purposes, convert this time into the local time of the seller."
}
},
"description": "This type defines the fields that describe a threshold promotion and includes the promotional discount, the items included in the promotion, and the rules that specify when the promotion is applied."
},
"ItemPromotionResponse": {
"type": "object",
"properties": {
"applyDiscountToSingleItemOnly": {
"type": "boolean",
"description": "If set to true
, the discount is applied only when the buyer purchases multiple quantities of a single item in the promotion. Otherwise, the promotional discount applies to multiple quantities of any items in the promotion. 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 promotion."
},
"budget": {
"description": "This sets the budget for the CODED_COUPON
promotion 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 promotion 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 promotion.", "$ref": "#/components/schemas/CouponConfiguration" }, "description": { "type": "string", "description": "Required for CODED_COUPON promotions, 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 promotion and is displayed under the offer tile that is shown on the seller's All Offers page and on the event page for the promotion. This tag line is not used with volume pricing promotions.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+\".
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 included in the promotion. 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": {
"type": "string",
"description": "The eBay marketplace ID of the site where the threshold promotion is hosted. Threshold promotions 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 StatesDRAFT
or SCHEDULED
. For implementation help, refer to eBay API documentation"
},
"promotionType": {
"type": "string",
"description": "Indicates the type of the promotion, either CODED_COUPON
, MARKDOWN_SALE
, ORDER_DISCOUNT
, or VOLUME_DISCOUNT
. For implementation help, refer to eBay API documentation"
},
"startDate": {
"type": "string",
"description": "The date and time the promotion starts in UTC format (yyyy-MM-ddThh:mm:ssZ
). For display purposes, convert this time into the local time of the seller."
}
},
"description": "This complex type defines the fields returned for an item (threshold) promotion."
},
"ItemsPagedCollection": {
"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"
},
"listings": {
"type": "array",
"description": "An array of the listings associated with a promotion.",
"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. 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"
},
"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/Error"
}
}
},
"description": "This type defines the fields for a paginated result set of promotions. 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",
"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": {
"type": "string",
"description": "The status of the keyword.ACTIVE
PAUSED
ARCHIVED
BROAD
EXACT
PHRASE
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": "A type that defines the keywords of the paged collection."
},
"KeywordRequest": {
"type": "object",
"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).BROAD
EXACT
PHRASE
BROAD
EXACT
PHRASE
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). EXACT
PHRASE
0
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/Error"
}
},
"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": {
"type": "string",
"description": "The match type for the negative keyword.EXACT
PHRASE
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.gte
, lte
, or both must contain a value if the seller wishes to use a price range."
}
},
"description": "The price range."
},
"PromotionDetail": {
"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."
},
"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 promotion and displayed under the offer tile that is shown on the seller's All Offers page and on the promotion'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+\".
yyyy-MM-ddThh:mm:ssZ
). For display purposes, convert this time into the local time of the seller."
},
"marketplaceId": {
"type": "string",
"description": "The eBay marketplace ID of the site where the promotion is hosted. Threshold promotions are supported on a select set of marketplaces while markdown promotions are supported on all eBay marketplaces. Valid values for threshold promotions are as follows:
EBAY_AU
= AustraliaEBAY_DE
= GermanyEBAY_ES
= SpainEBAY_FR
= FranceEBAY_GB
= Great BritainEBAY_IT
= ItalyEBAY_US
= United StatesDRAFT
or SCHEDULED
. For implementation help, refer to eBay API documentation"
},
"promotionType": {
"type": "string",
"description": "Indicates type of the promotion, either CODED_COUPON
, MARKDOWN_SALE
, ORDER_DISCOUNT
, or VOLUME_DISCOUNT
. For implementation help, refer to eBay API documentation"
},
"startDate": {
"type": "string",
"description": "The date and time the promotion 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 that describe a promotion. This includes all the information about a promotion except for the listings that are a part of the promotion."
},
"PromotionReportDetail": {
"type": "object",
"properties": {
"averageItemDiscount": {
"description": "The average item discount is the average discount that has been applied to each item in a promotion. This value is calculated as follows: CODED_COUPON
, MARKDOWN_SALE
, ORDER_DISCOUNT
, or VOLUME_DISCOUNT
. For implementation help, refer to eBay API documentation"
},
"totalDiscount": {
"description": "This is the monetary discount amount applied to the sale of items in a threshold promotion where the threshold has been met and the discount was applied. 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 in a paginated result set of seller promotions. 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",
"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. 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 in a paginated result set of promotion-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",
"properties": {
"currency": {
"type": "string",
"description": "The base currency applied to the value field to establish a monetary amount. CAD
. <
) and greater than (>
) characters.yyyy-MM-ddThh:mm:ss.sssZ
).yyyy-MM-ddThh:mm:ss.sssZ
).RUNNING
status. If the seller launches a campaign before the startDate, the campaign will be updated to SCHEDULED
status and will change to RUNNING
status at the time of the specified startDate."
}
},
"description": "This type defines the fields needed to create a quick setup PLA campaign. To create a quick setup campaign, a seller must specify the name, start date, and marketplace of the campaign. The seller must also specify the listing Ids of the items they want associated with the campaign."
},
"ReportMetadata": {
"type": "object",
"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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"metricMetadata": {
"type": "array",
"description": "A list containing the metadata for the metrics in the report.",
"items": {
"$ref": "#/components/schemas/MetricMetadata"
}
},
"reportType": {
"type": "string",
"description": "The report_type, as specified in the request to create the report task.COST_PER_SALE
.COST_PER_SALE
COST_PER_CLICK
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": { "type": "string", "description": "The ID of the eBay marketplace used by the report task. For implementation help, refer to eBay API documentation" }, "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.TSV_GZIP
is supported. For implementation help, refer to eBay API documentation"
},
"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. 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. 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."
},
"RuleCriteria": {
"type": "object",
"properties": {
"excludeInventoryItems": {
"type": "array",
"description": "A list of seller inventory reference IDs to exclude from the promotion.Note: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent itemsNote: The request can have either excludeInventoryItems or excludeListingIds but not both.
Maximum: 100 parent itemsINVENTORY_BY_RULE
. INVENTORY_BY_RULE
or INVENTORY_ANY
."
},
"SelectedInventoryDiscount": {
"type": "object",
"properties": {
"discountBenefit": {
"description": "This container defines the promotional 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 promotion. 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 Promotions Manager promotions must support an electronic payment method.
", "$ref": "#/components/schemas/InventoryCriterion" }, "ruleOrder": { "type": "integer", "description": "For markdown promotions, 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).INVENTORY_BY_RULE
.INVENTORY_BY_RULE
. For implementation help, refer to eBay API documentation"
},
"listingConditionIds": {
"type": "array",
"description": "A comma-separated list of unique identifiers for the conditions of listings to be includedBROAD
EXACT
PHRASE
BROAD
EXACT
PHRASE
Default: 0
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.0
.",
"format": "int32"
}
},
"description": "A type that defines the keywords of the paged collection."
},
"TargetedBidRequest": {
"type": "object",
"properties": {
"keywords": {
"type": "array",
"description": "An array of keywords for which bids will be required. KEYWORD_INSIGHTS
",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"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.ADOPTED_KEYWORDS
",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"listingIds": {
"type": "array",
"description": "A set of comma-separated listing IDs for the specific listings you wish to retrieve suggested keywords. BROAD
EXACT
PHRASE
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", "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." }, "UpdateAdGroupRequest": { "type": "object", "properties": { "adGroupStatus": { "type": "string", "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:
ACTIVE
PAUSED
ARCHIVED
ACTIVE
PAUSED
ARCHIVED
ACTIVE
PAUSED
ARCHIVED
4.1
, 5.0
, 5.5
, ...0.01
, 10.75
, 99.99
,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.DYNAMIC
.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",
"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/Error"
}
},
"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": {
"type": "string",
"description": "The inventory reference type associated with the ad. The inventory reference type could be a SKU number or Inventory Item Group. For implementation help, refer to eBay API documentation"
},
"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",
"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. 4.1
, 5.0
, 5.5
, ...0.01
, 10.75
, 99.99
,2.0
and a maximum value of 100.0
."
}
},
"description": "This type specifies the bid percentage for an ad campaign."
},
"UpdateBiddingStrategyRequest": {
"type": "object",
"properties": {
"biddingStrategy": {
"type": "string",
"description": "The new bidding strategy for the specified Cost Per Click (CPC) campaign. For implementation help, refer to eBay API documentation"
}
},
"description": "This type defines the fields used in the updatedBiddingStrategy request."
},
"UpdateCampaignBudgetRequest": {
"type": "object",
"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.50.00
100.00
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.
\"audienceCodes\": \"code1\", \"code2\"
and the user wishes to add an audience code code3
, set the audienceCodes
value to \"audienceCodes\": \"code1\", \"code2\", \"code3\"
.AUTO
in order to use a category ID."
},
"categoryType": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"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.COUPON
campaign type is 4, and for every other campaign type is 10.MANUAL
in order to use this field.",
"items": {
"type": "string"
}
},
"itemSelectMode": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
},
"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.AUTO
.",
"$ref": "#/components/schemas/PriceRange"
},
"promotionId": {
"type": "string",
"description": "The ID of the promotion used for an email campaign if the emailCampaignType is set to COUPON
, SALE_EVENT
, or ORDER_DISCOUNT
, and promotionSelectModeEnum is set to MANUAL
.AUTO
, eBay will choose the promotion to include in the email campaign. If set to MANUAL
, the seller must specify the promotion in the promotionId field.COUPON
, SALE_EVENT
, or ORDER_DISCOUNT
. For implementation help, refer to eBay API documentation"
},
"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.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
. For implementation help, refer to eBay API documentation"
},
"subject": {
"type": "string",
"description": "The email campaign subject. The maximum length is 70 characters."
}
},
"description": "The update email campaign request payload"
},
"UpdateEmailCampaignResponse": {
"type": "object",
"properties": {
"emailCampaignId": {
"type": "string",
"description": "The unique eBay-assigned ID to the email campaign that is generated when the email campaign is created."
},
"emailCampaignStatus": {
"type": "string",
"description": "The email campaign status. See EmailCampaignStatusEnum for a list of email campaign statuses and their descriptions. For implementation help, refer to eBay API documentation"
}
}
},
"UpdateKeywordByKeywordIdRequest": {
"type": "object",
"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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
}
},
"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": {
"type": "string",
"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. For implementation help, refer to eBay API documentation"
}
},
"description": "A type that contains the fields for the UpdateKeyword request."
},
"UpdateKeywordResponse": {
"type": "object",
"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/Error"
}
},
"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": "List of warnings associated with this operation",
"items": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "A type that contains the fields for the UpdateKeyword response."
},
"UpdateNegativeKeywordIdRequest": {
"type": "object",
"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": {
"type": "string",
"description": "A field that defines the status of the negative keyword.
See NegativeKeywordStatusEnum for supported values. For implementation help, refer to eBay API documentation"
}
},
"description": "A type that defines the fields used to update a negative keyword."
},
"UpdateNegativeKeywordRequest": {
"type": "object",
"properties": {
"negativeKeywordStatus": {
"type": "string",
"description": "A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation"
}
},
"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/Error"
}
},
"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."
}
},
"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"
}
}
}
}
}
}
}