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.21.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) model, bulk ads may be directly created for the listing.

For each listing specified in the request, this method:

To create ads for a listing, specify their inventoryReferenceId and inventoryReferenceType, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to which you want to associate the ads using the campaign_id path parameter.

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.

Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns. operationId: bulkCreateAdsByInventoryReference 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.

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: The container for the bulk request to create ads for eBay inventory reference IDs. eBay inventory reference IDs are seller-defined IDs used by theInventory API. content: application/json: schema: description: The container for the bulk request to create ads for eBay inventory reference IDs. eBay inventory reference IDs are seller-defined IDs used by theInventory API. $ref: '#/components/schemas/BulkCreateAdsByInventoryReferenceRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkCreateAdsByInventoryReferenceResponse' '207': description: Multi Status '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. '35012': domain: API_MARKETING category: REQUEST description: The inventory reference ID {inventoryReferenceId} is not valid. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36106': domain: API_MARKETING category: REQUEST description: The 'adGroupId' is not supported for CPS funding model. '36108': domain: API_MARKETING category: REQUEST description: The 'adGroupId' is required for CPC funding model. '36210': domain: API_MARKETING category: REQUEST description: No adgroup found for adgroup id {ad_group_id}. '36219': domain: API_MARKETING category: REQUEST description: The ad group with ad group id {ad_group_id} has been archived. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call. '35072': domain: API_MARKETING category: BUSINESS description: InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP'. '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. '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_ads_by_listing_id: post: tags: - ad description: This method adds multiple listings to an existing Promoted Listings campaign using listingId values generated by the Trading API or Inventory API, or using values generated by an ad group ID.

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

Note: Ad groups are not required when adding listings to a smart targeting campaign.

For the ad group specified in the request, this method associates the ad with the specified ad group.

To create an ad for an ad group, specify the name of the ad group plus the defaultBid for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method.

You can specify one or more ad groups per campaign.

Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.

operationId: bulkCreateAdsByListingId parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associated the ads being created.

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: The container for the bulk request to create ads for eBay listing IDs. eBay listing IDs are generated by the Trading API and Inventory API when the listing is created on eBay. content: application/json: schema: description: The container for the bulk request to create ads for eBay listing IDs. eBay listing IDs are generated by the Trading API and Inventory API when the listing is created on eBay. $ref: '#/components/schemas/BulkCreateAdRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkAdResponse' '207': description: Multi Status '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. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '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' is not supported for CPS funding model. '36108': domain: API_MARKETING category: REQUEST description: The 'adGroupId' is required for CPC funding model. '36210': domain: API_MARKETING category: REQUEST description: No ad group found for ad group id {ad_group_id}. '36412': domain: API_MARKETING category: REQUEST description: Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again. '404': description: Not Found '409': description: Conflict 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. '35068': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call. '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. '36152': domain: API_MARKETING category: BUSINESS description: The 'bidPercentage' is not supported for CPC funding model. '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}/bulk_delete_ads_by_inventory_reference: post: tags: - ad description: This method works with listings created with the Inventory API.

The method deletes a set of ads, as specified by a list of inventory reference IDs, from the specified campaign. Inventory reference IDs are seller-defined IDs that are used with the Inventory API.

Pass the campaign_id as a path parameter and populate the payload with a list of inventoryReferenceId and inventoryReferenceType pairs that you want to delete.

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: bulkDeleteAdsByInventoryReference parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to delete a set of ads.

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 request works with listings created via the Inventory API.

The request is to delete a set of ads in bulk, as specified by a list of inventory reference IDs from the specified campaign. content: application/json: schema: description: This request works with listings created via the Inventory API.

The request is to delete a set of ads in bulk, as specified by a list of inventory reference IDs from the specified campaign. $ref: '#/components/schemas/BulkDeleteAdsByInventoryReferenceRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkDeleteAdsByInventoryReferenceResponse' '207': description: Multi Status '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}.' '35012': domain: API_MARKETING category: REQUEST description: The inventory reference ID {inventoryReferenceId} is not valid. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call. '35072': domain: API_MARKETING category: BUSINESS description: InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP' '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}/bulk_delete_ads_by_listing_id: post: tags: - ad description: This method works with listing IDs created with either the Trading API or the Inventory API.

The method deletes a set of ads, as specified by a list of listingID values from a Promoted Listings campaign. A listing ID value is generated by eBay when a seller creates a listing with either the Trading API and Inventory API.

Pass the campaign_id as a path parameter and populate the payload with the set of listing IDs that you want to delete.

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.

When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED. operationId: bulkDeleteAdsByListingId parameters: - name: campaign_id in: path description: This path parameter specifies the eBay-assigned identifier of the ad campaign for which to delete a set of ads.

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 request object defines the fields for the bulkDeleteAdsByListingId request. content: application/json: schema: description: This request object defines the fields for the bulkDeleteAdsByListingId request. $ref: '#/components/schemas/BulkDeleteAdRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkDeleteAdResponse' '207': description: Multi Status '400': description: Bad Request x-response-codes: errors: '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. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Business error x-response-codes: errors: '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs 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. '35078': domain: API_MARKETING category: BUSINESS description: To gain access to Promoted Listings, you must be in good standing with 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 /ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_reference: post: tags: - ad description: This method works with listings created with either the Trading API or the Inventory API.

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.

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 request object defines the fields for the BulkCreateAdsByInventoryReference request. content: application/json: schema: description: This request object defines the fields for the BulkCreateAdsByInventoryReference request. $ref: '#/components/schemas/BulkCreateAdsByInventoryReferenceRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkUpdateAdsByInventoryReferenceResponse' '207': description: Multi Status '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}.' '35012': domain: API_MARKETING category: REQUEST description: The inventory reference ID {inventoryReferenceId} is not valid. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call. '35072': domain: API_MARKETING category: BUSINESS description: InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP' '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. '35113': domain: API_MARKETING category: BUSINESS description: This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign. '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_update_ads_bid_by_listing_id: post: tags: - ad description: This method works with listings created with either the Trading API or the Inventory API.

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.

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 request object defines the fields for the BulkCreateAdsByListingId request. content: application/json: schema: description: This request object defines the fields for the BulkCreateAdsByListingId request. $ref: '#/components/schemas/BulkCreateAdRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkAdUpdateResponse' '207': description: Multi Status '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}.' '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. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing IDs or inventoryReference IDs in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35044': domain: API_MARKETING category: REQUEST description: No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again. '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. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Conflict 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. '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs or inventory reference IDs. Only {maxSupportedNumber} IDs are supported per call. '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. '35113': domain: API_MARKETING category: BUSINESS description: This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign. '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_update_ads_status: post: tags: - ad 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 works with listings created with either the Trading API or the Inventory API.

This method updates the status of ads in bulk.

Specify the campaign_id you want to update as a URI parameter, and configure the adGroupStatus in the request payload. operationId: bulkUpdateAdsStatus parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad statuses 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: The bulk request to update the ads. content: application/json: schema: description: The bulk request to update the ads. $ref: '#/components/schemas/BulkUpdateAdStatusRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkAdUpdateStatusResponse' '207': description: Multi Status '400': description: Bad Request x-response-codes: errors: '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35044': domain: API_MARKETING category: REQUEST description: No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again. '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. '404': description: Not Found '409': description: Conflict 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. '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing Ids or inventory reference Ids. Only {maxSupportedNumber} Ids 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. '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. '36160': domain: API_MARKETING category: BUSINESS description: This functionality is only supported for CPC funding model. '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_update_ads_status_by_listing_id: post: tags: - ad 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 works with listings created with either the Trading API or the Inventory API.

The method updates the status of ads in bulk, based on listing ID values.

Specify the campaign_id as a path parameter and supply a set of listing IDs with their updated adStatus 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 retrieve a list of seller inventory reference IDs. operationId: bulkUpdateAdsStatusByListingId parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being 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: The bulk request to update ads. content: application/json: schema: description: The bulk request to update ads. $ref: '#/components/schemas/BulkUpdateAdStatusByListingIdRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkAdUpdateStatusByListingIdResponse' '207': description: Multi Status '400': description: Bad Request x-response-codes: errors: '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. '35018': domain: API_MARKETING category: REQUEST description: There are duplicate listing Ids or inventoryReference Ids in this request. You must remove the duplicate. '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '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}. '35048': domain: API_MARKETING category: REQUEST description: The listing Id {listingId} is invalid or has ended. '35083': domain: API_MARKETING category: REQUEST description: The requested 'adStatus' is not valid. '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. '36412': domain: API_MARKETING category: REQUEST description: Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again. '404': description: Not Found '409': description: Conflict 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. '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. '35071': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing Ids or inventory reference Ids. Only {maxSupportedNumber} Ids are supported per call. '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. '35084': domain: API_MARKETING category: BUSINESS description: The Ad associated with listing Id {listingId} is archived. '35085': domain: API_MARKETING category: BUSINESS description: The 'adGroupId' {ad_group_id} does not exist under campaign {campaign_id}. '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}/ad: get: tags: - ad description: This method retrieves Promoted Listings ads that are associated with listings created with either the Trading API or the Inventory API.

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.

Use the getAdGroups method to retrieve the ad group ID for the ad group.

Note: This field only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. required: false schema: type: string - name: ad_status in: query description: A comma-separated list of ad statuses. The results will be filtered to only include the given statuses of the ad. If none are provided, all ads are returned.

See AdStatusEnum for supported values. required: false schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: limit in: query description: 'Specifies the maximum number of ads to return on a page in the paginated response.

Default: 10

Maximum: 500' required: false schema: type: string - name: listing_ids in: query description: A comma-separated list of listing IDs.

Note: The response includes only active ads. The results do not include listing IDs that are excluded by other conditions. required: false schema: type: string - name: offset in: query description: Specifies the number of ads to skip in the result set before returning the first ad in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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. '36412': domain: API_MARKETING category: REQUEST description: Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again. '404': description: Not Found '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 manual targeting 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.

Note: Ad groups are not required when adding listings to a smart targeting campaign.

For the ad group specified in the request, this method associates the ad with the specified ad group.

To create an ad for an ad group, specify the name of the ad group in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method.

You can specify one or more ad groups per campaign.

Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.

This call has no response payload. If the ad is successfully created, a 201 Created HTTP status code and the getAd URI of the ad are returned in the location header.

operationId: createAdByListingId parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associate the newly created ad.

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 request object defines the fields used in the createAdByListingId request. content: application/json: schema: description: This request object defines the fields used in the createAdByListingId request. $ref: '#/components/schemas/CreateAdRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the getAd URI of the newly created ad. The URI includes the newly created 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. '36412': domain: API_MARKETING category: REQUEST description: Campaigns where the 'campaignTargetingType' is 'SMART' do not support ad groups. Please remove the {adGroupFieldName} and try again. '404': description: Not Found '409': description: Conflict 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.

For Promoted Listings Standard (PLS) campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.

For each listing specified in the request, this method:

To create an ad for a listing, specify its inventoryReferenceId and inventoryReferenceType, 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.

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.

Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns. operationId: createAdsByInventoryReference parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which to associate the newly created ads.

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 request object defines the fields used in the createAdsByInventoryReference request. content: application/json: schema: description: This request object defines the fields used in the createAdsByInventoryReference request. $ref: '#/components/schemas/CreateAdsByInventoryReferenceRequest' required: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/AdReferences' '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. '35012': domain: API_MARKETING category: REQUEST description: The inventory reference ID {inventoryReferenceId} is not valid. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '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' is not supported for CPS funding model. '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. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '35072': domain: API_MARKETING category: BUSINESS description: InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the InventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP' '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}/ad/{ad_id}: get: tags: - ad description: This method retrieves the specified ad from the specified 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.

Use the getAds method to retrieve ad IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Ad' '400': description: Bad Request x-response-codes: errors: '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35044': domain: API_MARKETING category: REQUEST description: No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again. '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 delete: tags: - ad description: This method removes the specified ad from the specified campaign.

Pass the ID of the ad to delete with the ID of the campaign associated with the ad as path parameters to the call.

Call getCampaigns to get the current list of the seller's campaign IDs.

Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information.

When using the CPC funding model, use the bulkUpdateAdsStatusByListingId method to change the status of ads to ARCHIVED. operationId: deleteAd parameters: - name: ad_id in: path description: This path parameter specifies the unique identifier of the ad being deleted.

Use the getAds method to retrieve ad IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad being deleted.

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. '35044': domain: API_MARKETING category: REQUEST description: No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again. '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Business error x-response-codes: errors: '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. '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}/delete_ads_by_inventory_reference: post: tags: - ad description: This method works with listings that are managed with the Inventory API.

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.
When using the CPC funding model, use the bulkUpdateAdsStatusByInventoryReference method to change the status of ads to ARCHIVED. operationId: deleteAdsByInventoryReference parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being deleted.

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 request object defines the fields for the deleteAdsByInventoryReference request. content: application/json: schema: description: This request object defines the fields for the deleteAdsByInventoryReference request. $ref: '#/components/schemas/DeleteAdsByInventoryReferenceRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AdIds' '400': description: Bad Request x-response-codes: errors: '35012': domain: API_MARKETING category: REQUEST description: The inventory reference ID {inventoryReferenceId} is not valid. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Business error x-response-codes: errors: '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. '35072': domain: API_MARKETING category: BUSINESS description: InventoryReferenceId {inventoryReferenceId} is not eligible for Promoted Listings because it is a variation and variations can only be promoted using the parent ID to which it belongs. Replace this ID with the inventoryReferenceId of the parent and set 'inventoryReferenceType' to 'INVENTORY_ITEM_GROUP' '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}/get_ads_by_inventory_reference: get: tags: - ad description: This method retrieves Promoted Listings ads associated with listings that are managed with the Inventory API from the specified campaign.

Supply the campaign_id as a path parameter and use query parameters to specify the inventory_reference_id and inventory_reference_type pairs.

In the Inventory API, an inventory reference ID is either a seller-defined SKU value or an inventoryItemGroupKey (a seller-defined ID for an inventory item group, which is an entity that's used in the Inventory API to create a multiple-variation listing). To indicate a listing managed by the Inventory API, you must always specify both an inventory_reference_id and the associated inventory_reference_type.

Call getCampaigns to retrieve all of the seller's the 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. operationId: getAdsByInventoryReference parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ads being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: inventory_reference_id in: query description: This query parameter specifies the unique identifier of a single-item listing or a multi-variation listing.

To retrieve an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).

To retrieve an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API. required: 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.

See InventoryReferenceType for supported values. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Ads' '400': description: Bad Request x-response-codes: errors: '35012': domain: API_MARKETING category: REQUEST description: The inventory reference ID {inventoryReferenceId} is not valid. '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35040': domain: API_MARKETING category: REQUEST description: 'The inventory reference type is not valid. Valid values are: {inventoryReferenceTypeValues}.' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36106': domain: API_MARKETING category: REQUEST description: The 'adGroupId' is not supported for CPS funding model. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35064': domain: API_MARKETING category: BUSINESS description: This operation is only supported for key based campaigns. '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 /ad_campaign/{campaign_id}/ad/{ad_id}/update_bid: post: tags: - ad description: This method updates the bid percentage (also known as the "ad rate") for the specified ad in the specified campaign.

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.

Use the getAds method to retrieve ad IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad 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 for the updateBid request. content: application/json: schema: description: This type defines the fields for the updateBid request. $ref: '#/components/schemas/UpdateBidPercentageRequest' required: true responses: '204': description: No content '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}.' '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '35044': domain: API_MARKETING category: REQUEST description: No Ad found for 'ad_id' {ad_id}. Please correct the 'ad_id' and try again. '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. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Conflict 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. '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. '35113': domain: API_MARKETING category: BUSINESS description: This operation is not supported when selected adRateStratergy is DYNAMIC for the campaign. '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: 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.
This method retrieves ad groups for the specified campaigns.

Each campaign can only have one ad group.

In the request, supply the campaign_ids as path parameters.

Call getCampaigns to retrieve a list of the current campaign IDs for a seller. operationId: getAdGroups parameters: - name: ad_group_status in: query description: A comma-separated list of ad group statuses. The results will be filtered to only include the given statuses of the ad group.

See AdGroupStatusEnum for supported values. required: false schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad groups being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: limit in: query description: The number of results, from the current result set, to be returned in a single page. required: false schema: type: string - name: offset in: query description: 'The number of results that will be skipped in the result set. This is used with the limit field to control the pagination of the output.

For example, if the offset is set to 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.

Default: 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 x-response-codes: errors: '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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.
This method adds an ad group to an existing PLA campaign that uses manual targeting.

To create an ad group for a campaign, specify the defaultBid for the ad group in the payload of the request. Then specify the campaign to which the ad group should be associated using the campaign_id path parameter.

Each campaign can have one or more associated ad groups. operationId: createAdGroup parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign to associate with the ad group being created.

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 for the createAdGroup request. content: application/json: schema: description: This type defines the fields for the createAdGroup request. $ref: '#/components/schemas/CreateAdGroupRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the getAdGroup URL to the newly created ad group. The URL includes the newly assigned 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: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '36213': domain: API_MARKETING category: BUSINESS description: The campaign funding model should be CPC. Please check funding model for provided campaign id. '500': description: Internal Server Error 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.
This method retrieves the details of a specified ad group, such as the ad group’s default bid and status.

In the request, specify the campaign_id and ad_group_id as path parameters.

Call getCampaigns to retrieve a list of the current campaign IDs for a seller and call getAdGroups for the ad group ID of the ad group you wish to retrieve. operationId: getAdGroup parameters: - name: ad_group_id in: path description: This path parameter specifies the unique identifier of the ad group being retrieved.

Use the getAdGroups method to retrieve ad group IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the ad group being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AdGroup' '400': description: Bad Request x-response-codes: errors: '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36210': domain: API_MARKETING category: REQUEST description: No ad group found for ad group id {ad_group_id}. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '36213': domain: API_MARKETING category: BUSINESS description: The campaign funding model should be CPC. Please check funding model for provided campaign id. '500': description: Internal Server Error 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 put: 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.
This method updates the ad group associated with a campaign.

With this method, you can modify the default bid for the ad group, change the state of the ad group, or change the name of the ad group. Pass the ad_group_id you want to update as a URI parameter, and configure the adGroupStatus and defaultBid in the request payload.

Call getAdGroup to retrieve the current default bid and status of the ad group that you would like to update. operationId: updateAdGroup parameters: - name: ad_group_id in: path description: This path parameter specifies the unique identifier of the ad group that is being updated.

Use the getAdGroups method to retrieve ad group IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the ad group is 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 for the UpdateAdGroup request. content: application/json: schema: description: This type defines the fields for the UpdateAdGroup request. $ref: '#/components/schemas/UpdateAdGroupRequest' required: true 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}. '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. '36210': domain: API_MARKETING category: REQUEST description: No ad group found for ad group id {ad_group_id}. '36212': domain: API_MARKETING category: REQUEST description: The 'defaultBid' currency {defaultBidCurrency} should be the same as the daily budget. '36216': domain: API_MARKETING category: REQUEST description: The 'defaultBid' value {defaultBidValue} is not valid or missing. '36217': domain: API_MARKETING category: REQUEST description: The Ad Group name contains invalid characters. {notAllowedCharacters} are not allowed. '36224': domain: API_MARKETING category: REQUEST description: The 'defaultBid' or 'adGroupStatus' or 'name' value is required for this call. '36225': domain: API_MARKETING category: REQUEST description: '''ad_group_statuses'' value is invalid. It should be either ACTIVE, PAUSED or ARCHIVED.' '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '36213': domain: API_MARKETING category: BUSINESS description: The campaign funding model should be CPC. Please check funding model for provided campaign id. '500': description: Internal Server Error 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}/suggest_bids: 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.
This method allows sellers to retrieve the suggested bids for input keywords and match type. operationId: suggestBids parameters: - name: ad_group_id in: path description: This path parameter specifies the unique identifier of the ad group containing the keywords for which the bid suggestions will be provided.

Use the getAdGroups method to retrieve ad group IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keywords for which bid suggestions will be provided.

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: The data requested to retrieve the suggested bids. content: application/json: schema: description: The data requested to retrieve the suggested bids. $ref: '#/components/schemas/TargetedBidRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TargetedBidsPagedCollection' '400': description: Bad Request x-response-codes: errors: '35041': domain: API_MARKETING category: REQUEST description: The 'marketplaceId' is required. '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '35091': domain: API_MARKETING category: REQUEST description: You have exceeded the maximum number of requests. Only {maxSupportedNumber} are supported per call. '36210': domain: API_MARKETING category: REQUEST description: No ad group found for ad group id {ad_group_id}. '36301': domain: API_MARKETING category: REQUEST description: 'The provided keyword match type is not supported. Valid values are: {matchTypeValues}.' '36304': domain: API_MARKETING category: REQUEST description: The keywordText {keywordText} cannot be more than {maxKeywordTextLength} characters. '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} '404': description: Not Found '409': description: Conflict 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}.' '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. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.marketing /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords: 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.
This method allows sellers to retrieve a list of keyword ideas to be targeted for Promoted Listings campaigns. operationId: suggestKeywords parameters: - name: ad_group_id in: path description: This path parameter specifies the unique identifier of the ad group for which the keyword suggestions will be provided.

Use the getAdGroups method to retrieve ad group IDs. required: true schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which keyword suggestions will be provided.

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: The required data to retrieve suggested keywords. content: application/json: schema: description: The required data to retrieve suggested keywords. $ref: '#/components/schemas/TargetedKeywordRequest' required: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/TargetedKeywordsPagedCollection' '400': description: Bad Request x-response-codes: errors: '35013': domain: API_MARKETING category: REQUEST description: The listing Id {listingId} is not valid. '35041': domain: API_MARKETING category: REQUEST description: The 'marketplaceId' is required. '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}. '36301': domain: API_MARKETING category: REQUEST description: 'The provided keyword match type is not supported. Valid values are: {matchTypeValues}.' '70006': domain: API_MARKETING category: REQUEST description: The provided exclusion is not supported. Valid values are {supportedExclusions}. '70007': domain: API_MARKETING category: REQUEST description: The provided additionalInfo is not supported. Valid values are {supportedAdditionalInfo}. '404': description: Not Found '409': description: Conflict 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}.' '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. '35068': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing Ids. Only {maxSupportedNumber} listings are supported per call. '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 /ad_campaign/{campaign_id}/clone: post: tags: - campaign description: 'This method clones (makes a copy of) the specified campaign''s campaign criterion. The campaign criterion is a container for the fields that define the criteria for a rule-based campaign.

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

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: cloneCampaign parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign being cloned.

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 for a clone campaign request. content: application/json: schema: description: This type defines the fields for a clone campaign request. $ref: '#/components/schemas/CloneCampaignRequest' required: true responses: '201': description: Success headers: Location: schema: type: string description: The location response header contains the getCampaign URI to the retrieve the newly created campaign. content: application/json: schema: type: object '400': description: Bad Request x-response-codes: errors: '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}.' '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. '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for the CPC funding model. '404': description: Not Found '409': description: Business error x-response-codes: errors: '35062': domain: API_MARKETING category: BUSINESS description: The campaign with 'campaign_id' {campaign_id} has not ended yet. cloneCampaign is supported only for criterion based campaigns that have ended. '35065': domain: API_MARKETING category: BUSINESS description: This operation is only supported for criterion based campaigns. '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. '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. '35112': domain: API_MARKETING category: BUSINESS description: The 'adRateStrategy' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True. '35113': domain: API_MARKETING category: BUSINESS description: The 'dynamicAdRatePreferences' is currently only supported for criterion based campaign with 'autoselectFutureInventory' as True. '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. '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: get: tags: - campaign description: This method retrieves the details for all of the seller's defined campaigns. Request parameters can be used to retrieve a specific campaign, such as the campaign's name, the start and end date, the channel, the status, and the funding model (i.e., Cost Per Sale (CPS) or Cost Per Click (CPC)).

You can filter the result set by a campaign name, end date range, start date range, 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.

Use the getCampaigns method to retrieve a list of a seller''s campaign names.

Note: The results might be null if other filters exclude the campaign with this name.

Maximum: 1 campaign name' required: false schema: type: string - name: campaign_status in: query description: 'This query parameter specifies the status of the campaign(s) being retrieved.

Note: The results might not include all the campaigns with this status if other filters exclude them.
Valid values: See CampaignStatusEnum

Maximum: 1 status' required: false schema: type: string - name: channels in: query description: This query parameter specifies the channel for the the campaign(s) being retrieved.

The results will be filtered to only include campaigns with the specified channel. If not specified, all campaigns matching other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.

Valid Values: See ChannelEnum required: false schema: type: string - name: end_date_range in: query description: 'This query parameter specifies the range of a campaign''s end date. The results are filtered to include only campaigns with an end date that is within specified range.

Valid format (UTC):
Note:The results might not include all the campaigns ending on this date if other filters exclude them.' required: false schema: type: string - name: funding_strategy in: query description: This query parameter specifies the funding strategy for the campaign(s) being retrieved.

The results will be filtered to only include campaigns with the specified funding model. If not specified, all campaigns matching the other filter parameters will be returned. The results might not include these campaigns if other search conditions exclude them.

Valid Values: See FundingModelEnum required: false schema: type: string - name: limit in: query description: '

This query parameter specifies the maximum number of campaigns to return on a page in the paginated response.

Default: 10

Maximum: 500' required: false schema: type: string - name: offset in: query description: This query parameter specifies the number of campaigns to skip in the result set before returning the first report in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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: start_date_range in: query description: 'This query parameter specifies the range of a campaign''s start date in which to filter the results. The results are filtered to include only campaigns with a start date that is equal to this date or is within specified range.

Valid format (UTC):
Note: The results might not include all the campaigns with this start date if other filters exclude them.' required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CampaignPagedCollectionResponse' '400': description: Bad Request x-response-codes: errors: '35020': domain: API_MARKETING category: REQUEST description: The campaign name cannot be more than {maxCampaignNameLength} characters. '35023': domain: API_MARKETING category: REQUEST description: The request contains invalid characters. {notAllowedCharacters} are not allowed. '35027': domain: API_MARKETING category: REQUEST description: The date range {dateRange} is not valid. Ensure the beginning of the range is before the end of the range. '35028': domain: API_MARKETING category: REQUEST description: The format of the date range {dateRange} is invalid. The format for a date range is yyyy-MM-ddThh:mm:ss.sssZ..yyyy-MM-ddThh:mm:ss.sssZ or yyyy-MM-ddThh:mm:ss.sssZ.. or ..yyyy-MM-ddThh:mm:ss.sssZ. '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. '35043': domain: API_MARKETING category: REQUEST description: The campaign status of {campaignStatus} is either invalid or not supported for this operation. '35079': domain: API_MARKETING category: REQUEST description: Funding strategy needs to be one of {fundingStrategy} types. '409': description: Conflict x-response-codes: errors: '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: - campaign description: 'This method can be used to create a Promoted Listings Standard (PLS), Promoted Listings Advanced (PLA), or Offsite Ads campaign.

A Promoted Listings campaign is the structure in which you place the ads or ad group for the listings you wish to promote.

Note: Campaigns can only contain ads for a maximum of 50,000 items.
Promoted Listing Standard campaigns utilize a Cost Per Sale (CPS) funding model. Sellers can set the ad rate and bidding strategies that are right for their business through the adRateStrategy, biddingStrategy, bidPercentage fields. For more information on Promoted Listing Standard campaigns, see Promoted Listings Standard campaign flow.

Promoted Listings Advanced campaigns utilize a Cost per Click (CPC) funding model. Sellers can create a daily budget through the budget container and choose what channel that their ads appear on. In addition, PLA campaigns give sellers the ability to create ad groups and specify keywords to ensure their ads reach their intended audience. For more information on Promoted Listings Advanced campaigns, see Promoted Listings Advanced campaign flow.

Offsite Ads campaigns give sellers the ability to create their own advertising campaign and promote their eBay listing in leading external search channels. For more information on Offsite Ads campaigns, see Offsite Ads.

Note: Sellers can use the getAdvertisingEligibility method of the Account API v1 to determine their eligibility status for eBay advertising programs.
To create a basic campaign, supply: For details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see Promoted Listings campaign creation.' 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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: This type defines the fields for the create campaign request. content: application/json: schema: description: This type defines the fields for the create campaign request. $ref: '#/components/schemas/CreateCampaignRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the getCampaign URI to the newly created campaign. The URL includes the eBay-assigned 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}.' '35124': domain: API_MARKETING category: REQUEST description: 'The ''maxCpc'' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}.' '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. '35127': domain: API_MARKETING category: BUSINESS description: '''maxCPC'' is only supported for CPC funding model campaigns with on-site channels and smart targeting type.' '35128': domain: API_MARKETING category: BUSINESS description: '''campaignTargetingType'' is only supported for CPC funding model campaigns with on-site channels.' '35132': domain: API_MARKETING category: BUSINESS description: The 'biddingStrategy' field is not supported for CPS funding model. '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.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Campaign' '400': description: Bad Request x-response-codes: errors: '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 Developers 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 delete: tags: - campaign description: 'This method deletes the campaign specified by the campaign_id query parameter.

Note: You can only delete campaigns that have ended.

Call getCampaigns to retrieve the campaign_id and the campaign status (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.

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: '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. '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}/end: post: tags: - campaign description: This method ends an active (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.

operationId: endCampaign parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the RUNNING or PAUSED ad campaign that is being ended.

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/find_campaign_by_ad_reference: get: tags: - campaign description: This method retrieves the campaigns containing the listing that is specified using either a listing ID, or an inventory reference ID and inventory reference type pair. The request accepts either a listing_id, or an inventory_reference_id and inventory_reference_type pair, as used in the Inventory API.

eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing.

An inventory reference ID can be either a seller-defined SKU or inventoryItemGroupKey, as specified in the Inventory API.

Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information. operationId: findCampaignByAdReference parameters: - name: inventory_reference_id in: query description: This query parameter specifies the unique identifier of a single-item listing or a multi-variation listing associated with the campaign being retrieved.

To retrieve an campaign for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).

To retrieve an campaign for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.

Note: You must always pass in both inventory_reference_id and inventory_reference_type. required: false schema: type: string - name: inventory_reference_type in: query description: This query parameter specifies the type of the seller's inventory reference ID, which is a listing or group of items.

See InventoryReferenceTypeEnum for supported values.

Note: You must always pass in both inventory_reference_id and inventory_reference_type. required: false schema: type: string - name: listing_id in: query description: This query parameter specifies the unique identifier of the eBay listing associated with the ad being used to retrieve the campaign.

eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing. required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Campaigns' '400': description: Bad Request x-response-codes: errors: '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. '35031': domain: API_MARKETING category: REQUEST description: A 'listing_id' or an 'inventory_reference_id' and 'inventory_reference_type' is required for this call. '35032': domain: API_MARKETING category: REQUEST description: A 'listing_id' and an 'inventory_reference_id' cannot be used together in the same call. To use both in a campaign, you must submit two calls. '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 /ad_campaign/get_campaign_by_name: get: tags: - campaign description: This method retrieves the details of a single campaign, as specified with the campaign_name query parameter. Note that the campaign name you specify must be an exact, case-sensitive match of the name of the campaign you want to retrieve.

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

Use the getCampaigns method to retrieve a list of a seller's campaign names. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Campaign' '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. '35023': domain: API_MARKETING category: REQUEST description: The request contains invalid characters. {notAllowedCharacters} are not allowed. '35046': domain: API_MARKETING category: REQUEST description: No campaign found with the name {campaign_name}. '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 /ad_campaign/{campaign_id}/launch: post: tags: - campaign description: This method launches a Promoted Listings Advanced campaign created using the setupQuickCampaign method that is in 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.

Use the getCampaigns method to retrieve the campaign_id and the campaign status for all the seller's campaigns. operationId: launchCampaign parameters: - name: campaign_id in: path description: 'This path parameter specifies the unique eBay-assigned identifier of the ad campaign being launched.

For PLA campaigns created with the setupQuickCampaign method, the getCampaign URI for that campaign is returned in the Location response header. That URI will include the campaign_id value, which you will pass in as a path parameter in the launchCampaign method.

Note: The campaign ID value used here must be for a PLA campaign in 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: Conflict 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: Conflict 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.

operationId: resumeCampaign parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the paused ad campaign that is being resumed.

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: Conflict 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/setup_quick_campaign: post: tags: - campaign description: 'This method allows the seller to expedite the creation of a Promoted Listings Advanced (PLA) campaign.

Sellers only need to provide basic campaign information, such as the user-defined campaign name, the start date (and optionally the end date) of the campaign, the daily budget amount of the campaign, and the eBay marketplace where the campaign will be hosted. The seller must also identify the items they want to place in the campaign by adding the listing id of each item in the listingIds array of the request.

Using the provided listingIds, eBay creates ad groups for the campaign and organizes the listings into the appropriate ad group. eBay then adds keywords to each ad group and assigns each keyword a suggested bid.

By default, campaigns created using setupQuickCampaign utilize a FIXED keyword bidding strategy which means that a seller manually assigns and adjusts keyword bids for their CPC campaign.

Alternatively, once the campaign has been created, sellers may opt to utilize a DYNAMIC bidding strategy which means that eBay will manage a campaign''s keyword bids and automatically update them daily to the suggested bid.

For additional information about FIXED and DYNAMIC bidding strategies, refer to updateBiddingStrategy.

Campaigns created using this method will be in DRAFT status upon creation.

The location response header returned contains the getCampaign URI to retrieve the newly created campaign that is in draft status. Sellers should make this call to review and approve the campaign before they use the launchCampaign method to start the campaign.

Note: Promoted Listing Standard (PLS) campaigns are not supported. ' operationId: setupQuickCampaign 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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: This type defines the fields to create a quick setup Promoted Listings Advanced (PLA) campaign. content: application/json: schema: description: This type defines the fields to create a quick setup Promoted Listings Advanced (PLA) campaign. $ref: '#/components/schemas/QuickSetupRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the getCampaign URI to the newly created quick setup campaign. The URL includes the eBay-assigned 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.
This method allows sellers to retrieve the suggested budget for an Offsite Ads campaign. operationId: suggestBudget parameters: - name: X-EBAY-C-MARKETPLACE-ID in: header description: This header identifies the seller's eBay marketplace.

Note: If a marketplace ID value is not provided, the default value of EBAY_US is used.
See MarketplaceIdEnum for supported values. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SuggestBudgetResponse' '400': description: Bad Request x-response-codes: errors: '35041': domain: API_MARKETING category: REQUEST description: The 'marketplaceId' is required. '404': description: Not Found '409': description: Business error x-response-codes: errors: '35095': domain: API_MARKETING category: BUSINESS description: '''marketplaceId'' {marketplaceId} is not supported. Offsite Ads 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}/suggest_items: get: tags: - campaign 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 allows sellers to obtain ideas for listings, which can be targeted for Promoted Listings campaigns. operationId: suggestItems parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which suggestions are being provided.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: category_ids in: query description: 'Specifies the category ID that is used to limit the results. This refers to an exact leaf category (the lowest level in that category and has no children). This field can have one category ID, or a comma-separated list of IDs. To return all category IDs, set to null.

Use the getCategorySuggestions method to retrieve category IDs.

Maximum: 10 ' required: false schema: type: string - name: limit in: query description: 'Specifies the maximum number of campaigns to return on a page in the paginated response. If no value is specified, the default value is used.

Default: 10

Minimum: 1

Maximum: 1000' required: false schema: type: string - name: offset in: query description: Specifies the number of campaigns to skip in the result set before returning the first report in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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/TargetedAdsPagedCollection' '400': description: Bad Request x-response-codes: errors: '35008': domain: API_MARKETING category: REQUEST description: The category Id {categoryId} 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. '35041': domain: API_MARKETING category: REQUEST description: The 'marketplaceId' is required. '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '35090': domain: API_MARKETING category: REQUEST description: Category ID limit exceeded. You can pass up to a maximum of {maxCategoryLimit} category IDs per request. '404': description: Not Found '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}.' '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 /ad_campaign/{campaign_id}/update_ad_rate_strategy: post: tags: - campaign description: This method updates the ad rate strategy for an existing Promoted Listings Standard (PLS) rules-based ad campaign that uses the Cost Per Sale (CPS) funding model.

Specify the campaign_id as a path parameter. You can retrieve the campaign IDs for a seller by calling the getCampaigns method.

Note: This method only applies to the 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: updateAdRateStrategy parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the ad rate strategy is 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 request fields for the ad rate strategy that shall be updated. content: application/json: schema: description: This type defines the request fields for the ad rate strategy that shall be updated. $ref: '#/components/schemas/UpdateAdrateStrategyRequest' required: true responses: '204': description: No content '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}.' '35035': domain: API_MARKETING category: REQUEST description: The campaign with campaign id {campaign_id} has ended. '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}. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '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. '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}/update_bidding_strategy: post: tags: - campaign description: This method allows sellers to change the bidding strategy for a specified Cost Per Click (CPC) campaign that uses manual targeting. Available bidding strategies are:In addition, this method allows sellers to modify the maxCPC value of a smart targeting campaign.Note: This method only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. Refer to Funding Models in the Promoted Listings Playbook for more information. operationId: updateBiddingStrategy parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the keyword bidding strategy is 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 specifies the new value for the bidding strategy. content: application/json: schema: description: This type specifies the new value for the bidding strategy. $ref: '#/components/schemas/UpdateBiddingStrategyRequest' required: true 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}. '35124': domain: API_MARKETING category: REQUEST description: 'The ''maxCpc'' {maxCpc} is not valid. Minimum value: {minMaxCpc} , Maximum value:{maxMaxCpc}.' '35130': domain: API_MARKETING category: REQUEST description: The 'biddingStrategy' is required '36101': domain: API_MARKETING category: REQUEST description: This functionality is not supported for CPS funding model. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '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. '35126': domain: API_MARKETING category: BUSINESS description: 'The ''biddingStrategy'' isn''t applicable for campaigns with smart targeting type. ' '35127': domain: API_MARKETING category: BUSINESS description: '''maxCPC'' is only supported for CPC funding model campaigns with on-site channels and smart targeting type.' '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}/update_campaign_budget: post: tags: - campaign 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 updates the daily budget for a PLA campaign that uses the Cost Per Click (CPC) funding model.

A click occurs when an eBay user finds and clicks on the seller’s listing (within the search results) after using a keyword that the seller has created for the campaign. For each ad in an ad group in the campaign, each click triggers a cost, which gets subtracted from the campaign’s daily budget. If the cost of the clicks exceeds the daily budget, the Promoted Listings campaign will be paused until the next day.

Specify the campaign_id as a path parameter. You can retrieve the campaign IDs for a seller by calling the getCampaigns method. operationId: updateCampaignBudget parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which the budget is 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 request fields for the budget details that shall be updated. content: application/json: schema: description: This type defines the request fields for the budget details that shall be updated. $ref: '#/components/schemas/UpdateCampaignBudgetRequest' required: true 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}. '36100': domain: API_MARKETING category: REQUEST description: This functionality is not supported for CPS funding model. '36101': domain: API_MARKETING category: REQUEST description: The daily budget value format is a maximum of two decimal points. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '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. '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. '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. '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}/update_campaign_identification: post: tags: - campaign description: This method can be used to change the name of a campaign, as well as modify the start or end dates.

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: Conflict 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 manual targeting.

This method also sets the CPC rate for each keyword, depending on the selected bidding strategy, as follows:


In the request, supply the campaign_id as a path parameter.

Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller.' operationId: bulkCreateKeyword parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which a set of keywords is being created.

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: A type that defines the fields for the bulk request to create keywords. content: application/json: schema: description: A type that defines the fields for the bulk request to create keywords. $ref: '#/components/schemas/BulkCreateKeywordRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkCreateKeywordResponse' 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. '207': description: Multi Status '400': description: Bad Request x-response-codes: errors: '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '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}. '36315': domain: API_MARKETING category: REQUEST description: There are duplicate KeywordText and matchType combination in this request. You must remove the duplicate. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '36316': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of Keyword requests in a bulk request. Only {maxSupportedRequestNumberInBulk} Ids are supported per call. '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. '36322': domain: API_MARKETING category: BUSINESS description: Total keyword requests exceed the current AdGroup keyword capacity, which is {maxSupportedRequestNumber}. '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_update_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 updates the bids and statuses of keywords, in bulk, for an existing PLA campaign.

In the request, supply the campaign_id as a path parameter.

Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller. operationId: bulkUpdateKeyword parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which a set of keywords is 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: A type that defines the fields for the bulk request to update keywords. content: application/json: schema: description: A type that defines the fields for the bulk request to update keywords. $ref: '#/components/schemas/BulkUpdateKeywordRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkUpdateKeywordResponse' 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. '207': description: Multi Status '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}. '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. '36310': domain: API_MARKETING category: REQUEST description: No keyword found for keyword id {keyword_id}. '36313': domain: API_MARKETING category: REQUEST description: The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}. '36317': domain: API_MARKETING category: REQUEST description: The 'bid' or 'keywordStatus' is missing, either one is required for update. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '36316': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of Keyword requests in a bulk. Only {maxSupportedNumberInBulk} Ids are supported per call. '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: 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.
This method can be used to retrieve all of the keywords for ad groups in PLA campaigns that use the Cost Per Click (CPC) funding model.

In the request, specify the campaign_id as a path parameter. If one or more ad_group_ids are passed in the request body, the keywords for those ad groups will be returned. If ad_group_ids are not passed in the response body, the call will return all the keywords in the campaign.

Call the getCampaigns method to retrieve a list of current campaign IDs for a seller. operationId: getKeywords parameters: - name: ad_group_ids in: query description: A comma-separated list of ad group IDs. This query parameter is used if the seller wants to retrieve keywords from one or more specific ad groups. If this query parameter is not used, all keywords that are part of the CPC campaign are returned.

Use the getAdGroups method to retrieve the ad group IDs for a seller. required: false schema: type: string - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keyword(s) being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: keyword_status in: query description: A comma-separated list of keyword statuses. The results will be filtered to only include the given statuses of the keyword. If none are provided, all keywords are returned.

See KeywordStatusEnum for supported values. required: false schema: type: string - name: limit in: query description: '

Specifies the maximum number of results to return on a page in the paginated response.

Default: 10
Maximum: 500' required: false schema: type: string - name: offset in: query description: Specifies the number of results to skip in the result set before returning the first report in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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: Conflict x-response-codes: errors: '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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.
This method creates keywords using a specified campaign ID for an existing PLA campaign that uses manual targeting.

In the request, supply the campaign_id as a path parameter.

Call the suggestKeywords method to retrieve a list of keyword ideas to be targeted for PLA campaigns, and call the getCampaigns method to retrieve a list of current campaign IDs for a seller. operationId: createKeyword parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign for which a keyword is being created.

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: A type that defines the fields for the request to create a keyword. content: application/json: schema: description: A type that defines the fields for the request to create a keyword. $ref: '#/components/schemas/CreateKeywordRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the getKeyword URI of the newly created keyword. The URI includes the newly created 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: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '36319': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of create Keyword for an Ad Group. Only {maxSupportedNumber} Ids are supported per Ad Group. '36320': domain: API_MARKETING category: BUSINESS description: The keywordText {keywordText} cannot have total number of words more than {maxWordsInKeyword} words. '500': description: Internal Server Error 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.
This method retrieves details on a specific keyword from an ad group within a PLA campaign that uses the Cost Per Click (CPC) funding model.

In the request, specify the campaign_id and keyword_id as path parameters.

Call the getCampaigns method to retrieve a list of current campaign IDs for a seller and call the getKeywords method to retrieve their keyword IDs. operationId: getKeyword parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keyword being retrieved.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: keyword_id in: path description: This path parameter specifies the unique identifier of the keyword being retrieved.

Use the getKeywords method to retrieve keyword IDs. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Keyword' '400': description: Bad Request x-response-codes: errors: '35045': domain: API_MARKETING category: REQUEST description: No campaign found for campaign id {campaign_id}. '36310': domain: API_MARKETING category: REQUEST description: No keyword found for keyword id {keyword_id}. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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 put: 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 updates keywords using a campaign ID and keyword ID for an existing PLA campaign.

In the request, specify the campaign_id and keyword_id as path parameters.

Call the getCampaigns method to retrieve a list of current campaign IDs for a seller and call the getKeywords method to retrieve their keyword IDs. operationId: updateKeyword parameters: - name: campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the keyword being updated.

Use the getCampaigns method to retrieve campaign IDs. required: true schema: type: string - name: keyword_id in: path description: This path parameter specifies the unique identifier of the keyword being updated.

Use the getKeywords method to retrieve keyword 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: A type that defines the fields for the request to update a keyword. content: application/json: schema: description: A type that defines the fields for the request to update a keyword. $ref: '#/components/schemas/UpdateKeywordRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/UpdateKeywordResponse' 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. '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}. '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. '36310': domain: API_MARKETING category: REQUEST description: No keyword found for keyword id {keyword_id}. '36313': domain: API_MARKETING category: REQUEST description: The 'bid' value {bidValue} is more than maximum daily budget {maxDailyBudget}. '36317': domain: API_MARKETING category: REQUEST description: The 'bid' or 'keywordStatus' is missing, either one is required for update. '36318': domain: API_MARKETING category: REQUEST description: The keyword with 'keyword_id' {keyword_Id} is already archived and cannot be updated. '404': description: Not Found '409': description: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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 /bulk_create_negative_keyword: 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.
This method adds negative keywords, in bulk, to an existing ad group in a PLA campaign that uses manual targeting.

Specify the campaignId and adGroupId in the request body, along with the negativeKeywordText and negativeKeywordMatchType.

Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller. operationId: bulkCreateNegativeKeyword 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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: A type that defines the fields for the bulk request to create negative keywords. content: application/json: schema: description: A type that defines the fields for the bulk request to create negative keywords. $ref: '#/components/schemas/BulkCreateNegativeKeywordRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkCreateNegativeKeywordResponse' '207': description: Multi Status '400': description: Bad Request x-response-codes: errors: '35033': domain: API_MARKETING category: REQUEST description: At least one request is required for bulk requests. '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.' '36337': domain: API_MARKETING category: REQUEST description: You have exceeded the maximum number of negative keyword requests in a bulk. Only {maxSupportedNegativeKeywordRequestNumberInBulk} Ids are supported per call. '36338': domain: API_MARKETING category: REQUEST description: There are duplicate 'negativeKeywordText' and 'negativeKeywordMatchType' combination in this request. You must remove the duplicate(s). '36339': domain: API_MARKETING category: REQUEST description: Total negative keyword requests exceed the current AdGroup negative keyword capacity, which is {maxSupportedNegativeKeywordRequestNumber}. '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: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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 /bulk_update_negative_keyword: 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.
This method updates the statuses of existing negative keywords, in bulk.

Specify the negativeKeywordId and negativeKeywordStatus in the request body. operationId: bulkUpdateNegativeKeyword 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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: A type that defines the fields for the bulk request to update negative keyword statuses. content: application/json: schema: description: A type that defines the fields for the bulk request to update negative keyword statuses. $ref: '#/components/schemas/BulkUpdateNegativeKeywordRequest' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BulkUpdateNegativeKeywordResponse' '207': description: Multi Status '400': description: Bad Request x-response-codes: errors: '36337': domain: API_MARKETING category: REQUEST description: You have exceeded the maximum number of negative keyword requests in a bulk. Only {maxSupportedNegativeKeywordRequestNumberInBulk} Ids are supported per call. '36340': domain: API_MARKETING category: REQUEST description: No negative keyword found for negative keyword id {negativeKeywordId}. '36341': domain: API_MARKETING category: REQUEST description: There are duplicate negative keyword Ids in this request. You must remove the duplicate(s). '36342': domain: API_MARKETING category: REQUEST description: NegativeKeywordStatus is missing or invalid. It is required for update. '36343': domain: API_MARKETING category: REQUEST description: Negative keyword with negative keyword id {negativeKeywordId} is already archived and cannot be updated. '36348': domain: API_MARKETING category: REQUEST description: Negative keyword id 'negativeKeywordId' is required. '36349': domain: API_MARKETING category: REQUEST description: The 'negativeKeywordId' is invalid. '403': description: Forbidden '409': description: Conflict 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: 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.
This method can be used to retrieve all of the negative keywords for ad groups in PLA campaigns that use the Cost Per Click (CPC) funding model.

The results can be filtered using the campaign_ids, ad_group_ids, and negative_keyword_status query parameters.

Call the getCampaigns method to retrieve a list of current campaign IDs for a seller. operationId: getNegativeKeywords parameters: - name: ad_group_ids in: query description: A comma-separated list of ad group IDs.

This query parameter is used if the seller wants to retrieve the negative keywords from one or more specific ad groups. The results might not include these ad group IDs if other search conditions exclude them.

Use the getAdGroups method to retrieve the ad group IDs for a seller.

Required if the search results must be filtered to include negative keywords created at the ad group level. required: false schema: type: string - name: campaign_ids in: query description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the negative keywords being retrieved.

This query parameter is used if the seller wants to retrieve the negative keywords from a specific campaign. The results might not include these campaign IDs if other search conditions exclude them.

Note: Currently, only one campaign ID value is supported for each request.

Use the getCampaigns method to retrieve campaign IDs. required: false schema: type: string - name: limit in: query description: The number of results, from the current result set, to be returned in a single page. required: false schema: type: string - name: negative_keyword_status in: query description: A comma-separated list of negative keyword statuses.

This query parameter is used if the seller wants to filter the search results based on one or more negative keyword statuses.

See NegativeKeywordStatusEnum for supported values. required: false schema: type: string - name: offset in: query description: The number of results that will be skipped in the result set. This is used with the limit field to control the pagination of the output.

For example, if the offset is set to 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: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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.
This method adds a negative keyword to an existing ad group in a PLA campaign that uses manual targeting.

Specify the campaignId and adGroupId in the request body, along with the negativeKeywordText and negativeKeywordMatchType.

Call the getCampaigns method to retrieve a list of current campaign IDs for a specified seller. operationId: createNegativeKeyword 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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: A type that defines the fields for the request to create a negative keyword. content: application/json: schema: description: A type that defines the fields for the request to create a negative keyword. $ref: '#/components/schemas/CreateNegativeKeywordRequest' required: true responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the URI of the newly created negative keyword. The URI includes the newly created 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: Conflict x-response-codes: errors: '35089': domain: API_MARKETING category: BUSINESS description: We are currently testing a premium ads product with a small invite-only group. We will share more information when we are ready to expand. '35129': domain: API_MARKETING category: BUSINESS description: This method is not supported for campaigns with smart targeting type. '500': description: Internal Server Error 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.
This method retrieves details on a specific negative keyword.

In the request, specify the negative_keyword_id as a path parameter. operationId: getNegativeKeyword parameters: - name: negative_keyword_id in: path description: This path parameter specifies the unique identifier for the negative keyword being retrieved.

Use the getNegativeKeywords method to retrieve negative keyword IDs. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/NegativeKeyword' '400': description: Bad Request x-response-codes: errors: '36340': domain: API_MARKETING category: REQUEST description: No negative keyword found for negative keyword id {negativeKeywordId}. '403': description: Forbidden '404': description: Not Found '409': description: Conflict 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 put: 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.
This method updates the status of an existing negative keyword.

Specify the negative_keyword_id as a path parameter, and specify the negativeKeywordStatus in the request body. operationId: updateNegativeKeyword parameters: - name: negative_keyword_id in: path description: The unique identifier for the negative keyword.

This value is returned in the Location response header from the createNegativeKeyword method. 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: A type that defines the fields for the request to update a negative keyword. content: application/json: schema: description: A type that defines the fields for the request to update a negative keyword. $ref: '#/components/schemas/UpdateNegativeKeywordRequest' required: true responses: '204': description: Success '400': description: Bad Request x-response-codes: errors: '36340': domain: API_MARKETING category: REQUEST description: No negative keyword found for negative keyword id {negativeKeywordId}. '36342': domain: API_MARKETING category: REQUEST description: NegativeKeywordStatus is missing or invalid. It is required for update. '36343': domain: API_MARKETING category: REQUEST description: Negative keyword with negative keyword id {negativeKeywordId} is already archived and cannot be updated. '403': description: Forbidden '404': description: Not Found '409': description: Conflict 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 /ad_report/{report_id}: get: tags: - ad_report description: 'This call downloads the report as specified by the report_id path parameter.

Call createReportTask to schedule and generate a Promoted Listings report. All date values are returned in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).

Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.

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.

' operationId: getReport parameters: - name: report_id in: path description: This path parameter specifies the unique ID of the Promoted Listings report being retrieved.

Use the getReportTasks method to retrieve report IDs. required: true schema: type: string responses: '200': description: Success content: text/tab-separated-values: schema: type: object '400': description: Bad Request x-response-codes: errors: '35110': domain: API_MARKETING category: REQUEST description: The 'report_id' {report_id} was not found. Correct the 'report_id' and try the call again. '404': description: Not Found '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 /ad_report_metadata: get: tags: - ad_report_metadata description: This call retrieves information that details the fields used in each of the Promoted Listings reports. Use the returned information to configure the different types of Promoted Listings reports.

You can retrieve metadata for all report types,funding models and channels, or you can filter based on funding model and/or channel.

Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged. operationId: getReportMetadata parameters: - name: funding_model in: query description: This query parameter is used only if the user wants to see report metadata for a specific funding model. Refer to the FundingModelEnum type for supported values. required: false schema: type: string - name: channel in: query description: This query parameter is used only if the user wants to see COST_PER_CLICK report metadata for a specific channel. Refer to the ChannelEnum type for supported values.

Note: The channel parameter is only applicable for COST_PER_CLICK funding model. required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ReportMetadatas' '400': description: Bad Request x-response-codes: errors: '35121': domain: API_MARKETING category: REQUEST description: 'The ''fundingModel'' is invalid. Valid values are: {supportedFundingModels}.' '35125': domain: API_MARKETING category: REQUEST description: 'The ''channel'' is invalid. Valid values are: {supportedChannels}.' '35127': domain: API_MARKETING category: REQUEST description: The 'channels' are not supported for the 'fundingModel' {fundingModel}. '500': description: Internal Server Error x-response-codes: errors: '35001': domain: API_MARKETING category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope /ad_report_metadata/{report_type}: get: tags: - ad_report_metadata description: This call retrieves metadata that details the fields used by a specific Promoted Listings report type. Use the report_type path parameter to indicate metadata to retrieve.

This method does not use a request payload.

Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged. operationId: getReportMetadataForReportType parameters: - name: report_type in: path description: This path parameter specifies the name of the report type whose metadata you want to retrieve.

For details about available report types and their descriptions, refer to the ReportTypeEnum. required: true schema: type: string - name: funding_model in: query description: The funding model used in the report. The funding model must be compatible with the report type specified in the path parameter. Refer to the FundingModelEnum type for supported values. required: false schema: type: string - name: channel in: query description: The channel used in the report. The channel must be compatible with the report type specified in the path parameter. Refer to the ChannelEnum type for supported values.

Note: The channel parameter is only applicable for COST_PER_CLICK funding model. required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ReportMetadata' '400': description: Bad Request x-response-codes: errors: '35116': domain: API_MARKETING category: REQUEST description: 'Supplied ''report_type'' not found. Valid values are: {supportedReportTypes}.' '35121': domain: API_MARKETING category: REQUEST description: 'The ''fundingModel'' is invalid. Valid values are: {supportedFundingModels}.' '35125': domain: API_MARKETING category: REQUEST description: 'The ''channel'' is invalid. Valid values are: {supportedChannels}.' '35127': domain: API_MARKETING category: REQUEST description: The 'channels' are not supported for the 'fundingModel' {fundingModel}. '35132': domain: API_MARKETING category: REQUEST description: The 'channels' {supportedChannels} are not supported for the 'report_type' {reportType}. '35133': domain: API_MARKETING category: REQUEST description: The 'fundingModel' is not supported for the 'report_type' {reportType}. '403': description: Forbidden x-response-codes: errors: '35089': domain: API_MARKETING category: REQUEST description: You are currently not authorized to access the Promoted Listings Advanced program. Please contact support. '404': description: Not Found '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 /ad_report_task: get: tags: - ad_report_task description: 'This method returns information on all the existing report tasks related to a seller.

Use the report_task_statuses query parameter to control which reports to return. You can paginate the result set by specifying a limit, which dictates how many report tasks to return on each page of the response. Use the offset parameter to specify how many reports to skip in the result set before returning the first result.


Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.

' operationId: getReportTasks parameters: - name: limit in: query description: Specifies the maximum number of report tasks to return on a page in the paginated response.

Default: 10
Maximum: 500 required: false schema: type: string - name: offset in: query description: Specifies the number of report tasks to skip in the result set before returning the first report in the paginated response.

Combine offset with the limit query parameter to control the 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.

Default: 0 required: false schema: type: string - name: report_task_statuses in: query description: This query parameter filters the returned report tasks by their status. Supply a comma-separated list of the report statuses you want returned. The results are filtered to include only the report statuses you specify.

Note: The results might not include some report tasks if other search conditions exclude them.
See TaskStatusEnum for supported values. required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ReportTaskPagedCollection' '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 {offset}. '35109': domain: API_MARKETING category: REQUEST description: 'The ''report_task_statuses'' {invalid_report_task_statuses} is invalid. Valid values are: {supportedReportTaskStatuses}.' '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 post: tags: - ad_report_task description: 'This method creates a report task, which generates a Promoted Listings report based on the values specified in the call.

The report is generated based on the criteria you specify, including the report type, the report''s dimensions and metrics, the report''s start and end dates, the listings to include in the report, and more. Metrics are the quantitative measurements in the report while dimensions specify the attributes of the data included in the reports.

When creating a report task, you can specify the items you want included in the report. The items you specify, using either listingId or inventoryReference values, must be in a Promoted Listings campaign for them to be included in the report.

For details on the required and optional fields for each report type, see Promoted Listings reporting.

This call returns the URL to the report task in the Location response header, and the URL includes the report-task ID.

Reports often take time to generate and it''s common for this call to return an HTTP status of 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.

Note: The reporting of some data related to sales and ad-fees may require a 72-hour (maximum) adjustment period which is often referred to as the Reconciliation Period. Such adjustment periods should, on average, be minimal. However, at any given time, the payments tab may be used to view those amounts that have actually been charged.
Note: This call fails if you don''t submit all the required fields for the specified report type. Fields not supported by the specified report type are ignored. Call getReportMetadata to retrieve a list of the fields you need to configure for each Promoted Listings report type.

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.

' operationId: createReportTask 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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: The container for the fields that define the report task. content: application/json: schema: description: The container for the fields that define the report task. $ref: '#/components/schemas/CreateReportTask' required: true responses: '202': description: Accepted '400': description: Bad Request x-response-codes: errors: '35012': domain: API_MARKETING category: REQUEST description: The 'inventoryReferenceId' {inventoryReferenceId} is not valid. '35013': domain: API_MARKETING category: REQUEST description: The 'listingId' {listingId} is not valid. Correct the 'listingId' and try the call again. '35040': domain: API_MARKETING category: REQUEST description: The 'inventoryReferenceType' {inventoryReferenceType} is not supported. '35041': domain: API_MARKETING category: REQUEST description: 'A ''marketplaceId'' is required. Supported marketplaces are: {supportedMarketplaces}' '35045': domain: API_MARKETING category: REQUEST description: No campaign found for {campaignId}. '35090': domain: API_MARKETING category: REQUEST description: dateFrom and dateTo span exceeds maximum allowed. Only up to {maxDayRange} days are supported. '35100': domain: API_MARKETING category: REQUEST description: Campaign ID is required for this call. '35102': domain: API_MARKETING category: REQUEST description: The {date_key} date is required for this call. '35103': domain: API_MARKETING category: REQUEST description: The date cannot be in future. '35104': domain: API_MARKETING category: REQUEST description: The report start date {dateFrom} cannot be after the end date {dateTo}. '35105': domain: API_MARKETING category: REQUEST description: The report 'dateFrom' {dateFrom} is out of range. Reports are limited up to {maxDays} days in the past. '35106': domain: API_MARKETING category: REQUEST description: The 'dimensionKey' {dimensionKey} is not valid. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls. '35107': domain: API_MARKETING category: REQUEST description: The 'dimensionKey' {dimensionKey} is not supported for the 'reportType' {reportType}. To see the supported dimension keys for a report, use one of the 'Get Metadata' calls. '35108': domain: API_MARKETING category: REQUEST description: The 'annotationKey' {annotationKey} is not supported for the 'dimensionKey' {dimensionKey}. To see the supported annotation and dimension keys for a report, use one of the 'Get Metadata' calls. '35111': domain: API_MARKETING category: REQUEST description: The 'inventoryReferenceId' {inventoryReferenceId} is not valid. '35113': domain: API_MARKETING category: REQUEST description: The listing ID is required for this call. '35114': domain: API_MARKETING category: REQUEST description: 'The ''reportType'' is invalid. Valid values are: {supportedReportTypes}.' '35115': domain: API_MARKETING category: REQUEST description: The 'metricKey' {metricKey} is not supported for the 'reportType' {reportType}. To see the supported metric keys for a report, use one of the 'Get Metadata' calls. '35118': domain: API_MARKETING category: REQUEST description: 'The ''reportFormat'' is missing or invalid. Valid values are: {supportedReportFormats}' '35119': domain: API_MARKETING category: REQUEST description: 'The minimum set of ''dimensionKey'' is not provided for the ''reportType'' {reportType}. Minimum required dimensionKeys are: {minimumDimensionKeys}' '35120': domain: API_MARKETING category: REQUEST description: 'At least one ''metricKey'' must be provided for ''reportType'' {reportType}. Valid metricKeys are: {supportedMetricKeys}' '35121': domain: API_MARKETING category: REQUEST description: 'The ''fundingModel'' is invalid. Valid values are: {supportedFundingModels}.' '35122': domain: API_MARKETING category: REQUEST description: The metric key is not supported for the funding model. '35123': domain: API_MARKETING category: REQUEST description: The 'dimensionKey' {dimensionKey} is not valid for the 'fundingModel' {fundingModel} '35124': domain: API_MARKETING category: REQUEST description: 'Multiple funding models are not supported. Please use one of the following funding models: {supportedFundingModels}' '35125': domain: API_MARKETING category: REQUEST description: 'The ''channel'' is invalid. Valid values are: {supportedChannels}.' '35126': domain: API_MARKETING category: REQUEST description: 'Multiple channels are not supported. Please use one of the following channels: {supportedChannels}' '35127': domain: API_MARKETING category: REQUEST description: The 'channels' are not supported for the 'fundingModel' {fundingModel} '35128': domain: API_MARKETING category: REQUEST description: The 'dimensionKey' {dimensionKey} is not valid for the 'channels' {supportedChannels} '35129': domain: API_MARKETING category: REQUEST description: The 'metricKey' {metricKey} is not supported for the 'channels' {supportedChannels} '35130': domain: API_MARKETING category: REQUEST description: The 'annotationKey' {annotationKey} is not supported for the 'fundingModel' {fundingModel}. '35131': domain: API_MARKETING category: REQUEST description: The 'annotationKey' {annotationKey} is not supported for the 'channels' {supportedChannels} '403': description: Forbidden x-response-codes: errors: '35089': domain: API_MARKETING category: REQUEST description: You are currently not authorized to access the Promoted Listings Advanced program. Please contact support '35091': domain: API_MARKETING category: REQUEST description: '''additionalRecords'' are supported only with COST_PER_CLICK FundingModel and non-performing data is applicable for account level reports with no Day level dimension. ''additionalRecords'' are applicable for reportTypes {supportedReportTypes}' '409': description: Conflict x-response-codes: errors: '35051': domain: API_MARKETING category: BUSINESS description: 'The ''marketplaceId'' {marketplaceId} is not supported. Supported marketplaces are: {supportedMarketplaces}' '35068': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of listing IDs. Only {maxSupportedListings} listings are supported per call. '35101': domain: API_MARKETING category: BUSINESS description: You have exceeded the maximum number of campaign IDs. Only {maxSupportedCampaigns} campaigns are supported per call. '35112': domain: API_MARKETING category: BUSINESS description: The maximum number {maxSupportedInventoryReferences} of inventory references has been exceeded. '500': description: Internal Server Error x-response-codes: errors: '35001': domain: API_MARKETING category: APPLICATION description: There was a problem with an eBay internal system or process. Contact eBay Developer Technical Support for assistance. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.marketing /ad_report_task/{report_task_id}: get: tags: - ad_report_task description: 'This call returns the details of a specific Promoted Listings report task, as specified by the report_task_id path parameter.

The report task includes the report criteria (such as the report dimensions, metrics, and included listing) and the report-generation rules (such as starting and ending dates for the specified report task).

Report-task IDs are generated by eBay when you call createReportTask. Get a complete list of a seller''s report-task IDs by calling getReportTasks.


Important!For ad_report and ad_report_task methods, the API call limit is subject to a per user quota. These API calls can only be executed a maximum of 200 times per hour for each seller/user. If the number of calls per hour exceeds this limit, any new calls will be blocked for the next hour.

' operationId: getReportTask parameters: - name: report_task_id in: path description: This path parameter specifies the unique identifier of the report task being retrieved.

Use the getReportTasks method to retrieve report task Ids. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ReportTask' '400': description: Bad Request x-response-codes: errors: '35140': domain: API_MARKETING category: REQUEST description: No ReportTask found for 'report_task_id' {report_task_id}. Please correct the 'report_task_id' and try again. '404': description: Not found '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 delete: tags: - ad_report_task description: 'This call deletes the report task specified by the report_task_id path parameter. This method also deletes any reports generated by the 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.

' operationId: deleteReportTask parameters: - name: report_task_id in: path description: This path parameter specifies the unique identifier of the report task being deleted.

Use the getReportTasks method to retrieve report task Ids. required: true schema: type: string responses: '204': description: No Content '400': description: Bad Request x-response-codes: errors: '35140': domain: API_MARKETING category: REQUEST description: No ReportTask found for 'report_task_id' {report_task_id}. Please correct the 'report_task_id' and try again. '404': description: Not found '409': description: Conflict x-response-codes: errors: '35141': domain: API_MARKETING category: BUSINESS description: The Report Task with 'report_task_id' {report_task_id} is being modified. Please wait a few minutes and try 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. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.marketing /item_price_markdown: post: tags: - item_price_markdown description: This method creates an item price markdown promotion (know simply as a "markdown promotion") where a discount amount is applied directly to the items included the promotion. Discounts can be specified as either a monetary amount or a percentage off the standard sales price. eBay highlights promoted items by placing teasers for the items throughout the online sales flows.

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.

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: This type defines the fields that describe an item price markdown promotion. content: application/json: schema: description: This type defines the fields that describe an item price markdown promotion. $ref: '#/components/schemas/ItemPriceMarkdown' required: false responses: '201': description: Created headers: Location: schema: type: string description: The location response header contains the URL to the newly created item price markdown promotion. The URL includes the eBay-assigned 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: Conflict 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.

Call getPromotions to retrieve the IDs of a seller's promotions. operationId: getItemPriceMarkdownPromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the promotion you want to retrieve plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

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

The parameters you are allowed to update with this request depend on the status of the promotion you''re updating: ' operationId: updateItemPriceMarkdownPromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the promotion you want to update plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: This type defines the fields that describe an item price markdown promotion. content: application/json: schema: description: This type defines the fields that describe an item price markdown promotion. $ref: '#/components/schemas/ItemPriceMarkdown' required: false responses: '200': description: Success 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). '345064': domain: API_MARKETING category: REQUEST description: You have moved inventory between discountBenefit containers or have the same inventory in multiple discountBenefit containers. For help, see the documentation for this call. '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. '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. '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. '38225': domain: API_MARKETING category: REQUEST description: You cannot update a promotion that has ended. '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. '38232': domain: API_MARKETING category: REQUEST description: You cannot update the promotion discount for an active promotion. '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}. '38260': domain: API_MARKETING category: REQUEST description: To update the start date of a promotion, the promotion must be in draft or scheduled state. '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. '38269': domain: API_MARKETING category: REQUEST description: The promotion ID does not match any of the seller's promotions. '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. '345065': domain: API_MARKETING category: REQUEST description: You cannot change the status of aa SCHEDULED promotion to DRAFT. For help, see the documentation for this call. '345070': domain: API_MARKETING category: REQUEST description: The giving discount ID does not exist in the promotion. For help, see the documentation for this call. '345071': domain: API_MARKETING category: REQUEST description: The giving discount type is not consistent with existing active promotion. For help, see the documentation for this call. '345072': domain: API_MARKETING category: REQUEST description: The giving inventory criterion type is not consistent with existing active promotion. For help, see the documentation for this call. '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 cannot specify Rules or inventory items when using the Inventory by ALL 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. '404': description: Not Found '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, please contact support. security: - api_auth: - https://api.ebay.com/oauth/api_scope/sell.marketing delete: tags: - item_price_markdown description: This method deletes the item price markdown promotion specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.

You can delete any promotion with the exception of those that are currently active (RUNNING). To end a running promotion, call updateItemPriceMarkdownPromotion and adjust the endDate field as appropriate. operationId: deleteItemPriceMarkdownPromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the promotion you want to delete plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: This type defines the fields that describe an item promotion. content: application/json: schema: description: This type defines the fields that describe an item promotion. $ref: '#/components/schemas/ItemPromotion' required: false responses: '201': description: Created headers: Location: schema: type: string description: URL location of new item promotion. content: application/json: schema: $ref: '#/components/schemas/BaseResponse' 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 you 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. '345137': domain: API_MARKETING category: REQUEST description: '''priority'' can not be set for this promotion type. For help, see the documentation for this call.' '345138': domain: API_MARKETING category: REQUEST description: '''description'' can not be set for this promotion type. For help, see the documentation for this call.' '345139': domain: API_MARKETING category: REQUEST description: '''applyDiscountToSingleItemOnly'' can not be set for this promotion type. For help, see the documentation for this call.' '345140': domain: API_MARKETING category: REQUEST description: '''promotionImageUrl'' can not be set for this promotion type. For help, see the documentation for this call.' '345142': domain: API_MARKETING category: REQUEST description: '''applyDiscountToSingleItemOnly'' is currently not supported for this Marketplace ID. For help, see the documentation for this call.' '345143': domain: API_MARKETING category: REQUEST description: '''couponType'' can not be set for this promotion type. For help, see the documentation for this call.' '345144': domain: API_MARKETING category: REQUEST description: '''maxCouponRedemptionPerUser'' can not be set for this promotion type. For help, see the documentation for this call.' '345145': domain: API_MARKETING category: REQUEST description: '''maxDiscountAmount'' can not be set for this promotion type. For help, see the documentation for this call.' '345146': domain: API_MARKETING category: REQUEST description: '''budget'' can not be set for this promotion type. For help, see the documentation for this call.' '345147': domain: API_MARKETING category: REQUEST description: '''couponCode'' can not be set for this promotion type. For help, see the documentation for this call.' '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. '38205': domain: API_MARKETING category: REQUEST description: The Marketplace ID is not recognized or is not eligible for promotions. '38207': domain: API_MARKETING category: REQUEST description: The promotion priority is invalid. Please check and try the call again. '38218': domain: API_MARKETING category: REQUEST description: A valid entry is required for {fieldName}. '38219': domain: API_MARKETING category: REQUEST description: Zonks! 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. '38236': domain: API_MARKETING category: REQUEST description: The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call. '38237': domain: API_MARKETING category: REQUEST description: 'The request can have only one of these fields: ''minQuantity'', ''forEachQuantity'', ''minAmount'', or ''forEachAmount'' in ''discountSpecification''. 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. '38239': domain: API_MARKETING category: REQUEST description: 'The request can have only one of these fields: ''percentageOffOrder'', ''amountOffOrder'', ''percentageOffItem'', or ''amountOffItem'' in ''discountBenefit''. 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. '38241': domain: API_MARKETING category: REQUEST description: This discount rule combination is currently not supported. 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''.' '38253': domain: API_MARKETING category: REQUEST description: The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call. '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}. '38257': domain: API_MARKETING category: REQUEST description: This promotion type supports only one discount rule for the item promotion. '38260': domain: API_MARKETING category: REQUEST description: To update the start date of a promotion, the promotion must be in draft or scheduled state. '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. '38265': domain: API_MARKETING category: REQUEST description: Number of discount items is greater than the quantity specified in 'DiscountSpecification'. '38267': domain: API_MARKETING category: REQUEST description: The 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call. '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. '345118': domain: API_MARKETING category: REQUEST description: You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion. '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. '345124': domain: API_MARKETING category: REQUEST description: Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory. '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. '345127': domain: API_MARKETING category: REQUEST description: Category aspects are not supported in this version. '345128': domain: API_MARKETING category: REQUEST description: The minimum discount rules required for volume discount promotions are {numOfDiscountRules} '345129': domain: API_MARKETING category: REQUEST description: The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call. '345130': domain: API_MARKETING category: REQUEST description: You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion. '345131': domain: API_MARKETING category: REQUEST description: Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule. '345132': domain: API_MARKETING category: REQUEST description: The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call. '345133': domain: API_MARKETING category: REQUEST description: Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions. '345134': domain: API_MARKETING category: REQUEST description: This promotionType is currently not supported. For help, see the documentation for this call. '345136': domain: API_MARKETING category: REQUEST description: The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call. '345137': domain: API_MARKETING category: REQUEST description: The 'couponCode' data is missing for coded coupon promotions. For help, see the documentation for this call. '345138': domain: API_MARKETING category: REQUEST description: The 'couponCode' value is invalid. For help, see the documentation for this call. '345139': domain: API_MARKETING category: REQUEST description: The 'couponType' data is missing for coded coupon promotions. For help, see the documentation for this call. '345140': domain: API_MARKETING category: REQUEST description: The 'couponType' value is invalid. For help, see the documentation for this call. '345141': domain: API_MARKETING category: REQUEST description: The 'maxDiscountAmount' data is missing for coded coupon promotions. For help, see the documentation for this call. '345142': domain: API_MARKETING category: REQUEST description: The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call. '345143': domain: API_MARKETING category: REQUEST description: The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call. '345144': domain: API_MARKETING category: REQUEST description: The 'budget' value is invalid. For help, see the documentation for this call. '345145': domain: API_MARKETING category: REQUEST description: A coupon with this 'couponCode' already exists. Please try a different 'couponCode'. '345146': domain: API_MARKETING category: REQUEST description: The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call. '345147': domain: API_MARKETING category: REQUEST description: '''promotionType'' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call.' '345148': domain: API_MARKETING category: REQUEST description: The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value. '409': description: Business Error x-response-codes: errors: '38243': domain: API_MARKETING category: BUSINESS description: The 'minQuantity' value is invalid. This value must be an integer. '38244': domain: API_MARKETING category: BUSINESS description: The 'forEachQuantity' value is invalid. This value must be an integer. '38245': domain: API_MARKETING category: BUSINESS description: The 'minAmount' value is invalid. For help, see the documentation for this call. '38246': domain: API_MARKETING category: BUSINESS description: The 'forEachAmount' value is invalid. For help, see the documentation for this call. '38247': domain: API_MARKETING category: BUSINESS description: The 'numberOfDiscountedItems' value is invalid. This value must be an integer. '38248': domain: API_MARKETING category: BUSINESS description: The 'percentOffItem' value is invalid. For help, see the documentation for this call. '38249': domain: API_MARKETING category: BUSINESS description: The 'percentOffOrder' 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. '38251': domain: API_MARKETING category: BUSINESS description: The 'amountOffOrder' value is invalid. For help, see the documentation for this call. '38266': domain: API_MARKETING category: BUSINESS description: The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value. '38268': domain: API_MARKETING category: BUSINESS description: The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'. '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_promotion/{promotion_id}: get: tags: - item_promotion description: This method returns the complete details of the threshold promotion specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions. operationId: getItemPromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the promotion you want to retrieve plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

' operationId: updateItemPromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the promotion you want to update plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

For more information, refer to HTTP request headers. required: true schema: type: string requestBody: description: This type defines the fields that describe an item promotion. content: application/json: schema: description: This type defines the fields that describe an item promotion. $ref: '#/components/schemas/ItemPromotion' required: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BaseResponse' 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 you 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. '345137': domain: API_MARKETING category: REQUEST description: '''priority'' can not be set for this promotion type. For help, see the documentation for this call.' '345138': domain: API_MARKETING category: REQUEST description: '''description'' can not be set for this promotion type. For help, see the documentation for this call.' '345139': domain: API_MARKETING category: REQUEST description: '''applyDiscountToSingleItemOnly'' can not be set for this promotion type. For help, see the documentation for this call.' '345140': domain: API_MARKETING category: REQUEST description: '''promotionImageUrl'' can not be set for this promotion type. For help, see the documentation for this call.' '345142': domain: API_MARKETING category: REQUEST description: '''applyDiscountToSingleItemOnly'' is currently not supported for this Marketplace ID. For help, see the documentation for this call.' '345143': domain: API_MARKETING category: REQUEST description: '''couponType'' can not be set for this promotion type. For help, see the documentation for this call.' '345144': domain: API_MARKETING category: REQUEST description: '''maxCouponRedemptionPerUser'' can not be set for this promotion type. For help, see the documentation for this call.' '345145': domain: API_MARKETING category: REQUEST description: '''maxDiscountAmount'' can not be set for this promotion type. For help, see the documentation for this call.' '345146': domain: API_MARKETING category: REQUEST description: '''budget'' can not be set for this promotion type. For help, see the documentation for this call.' '345147': domain: API_MARKETING category: REQUEST description: '''couponCode'' can not be set for this promotion type. For help, see the documentation for this call.' '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. '38207': domain: API_MARKETING category: REQUEST description: The promotion priority is invalid. Please check and try the call again. '38210': domain: API_MARKETING category: REQUEST description: You cannot change the priority of a promotion that is ended or deleted. '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. '38225': domain: API_MARKETING category: REQUEST description: You cannot update a promotion that has ended. '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. '38232': domain: API_MARKETING category: REQUEST description: You cannot update the promotion discount for an active promotion. '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. '38236': domain: API_MARKETING category: REQUEST description: The 'discountSpecification' data is missing, which is required by this call. For help, see the documentation for this call. '38237': domain: API_MARKETING category: REQUEST description: 'The request can have only one of these fields: ''minQuantity'', ''forEachQuantity'', ''minAmount'', or ''forEachAmount'' in ''discountSpecification''. 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. '38239': domain: API_MARKETING category: REQUEST description: 'The request can have only one of these fields: ''percentageOffOrder'', ''amountOffOrder'', ''percentageOffItem'', or ''amountOffItem'' in ''discountBenefit''. 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. '38241': domain: API_MARKETING category: REQUEST description: This discount rule combination is currently not supported. 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''.' '38253': domain: API_MARKETING category: REQUEST description: The data combination of 'DiscountSpecification' and 'DiscountBenefit' is not valid for this promotion type. For help, see the documentation for this call. '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}. '38257': domain: API_MARKETING category: REQUEST description: This promotion type supports only one discount rule for the item promotion. '38260': domain: API_MARKETING category: REQUEST description: To update the start date of a promotion, the promotion must be in draft or scheduled state. '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. '38265': domain: API_MARKETING category: REQUEST description: Number of discount items is greater than the quantity specified in 'DiscountSpecification'. '38267': domain: API_MARKETING category: REQUEST description: The 'DiscountBenefit.amountOffOrder' field cannot be used with the 'DiscountSpecification.numberOfDiscountedItems' field. This parameter is reserved for Buy x, Get x discounts. For help, see the documentation for this call. '38269': domain: API_MARKETING category: REQUEST description: The promotion ID does not match any of the seller's promotions. '38270': domain: API_MARKETING category: REQUEST description: The currency type does not match what is used for the Marketplace ID submitted. '38271': domain: API_MARKETING category: REQUEST description: Only new or scheduled promotions can be saved as a draft. '345077': domain: API_MARKETING category: REQUEST description: You cannot update a promotion that was not created through the API. '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. '345118': domain: API_MARKETING category: REQUEST description: You can specify only one of Inventory Items or Listing IDs in the Exclusion Criterion. '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 cannot specify Rules or inventory items when using the Inventory by ALL 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. '345124': domain: API_MARKETING category: REQUEST description: Exclusions are currently limited to a maximum of 100 parent items, when entering Inventory Items or Listing IDs, or choosing from live inventory. '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. '345127': domain: API_MARKETING category: REQUEST description: Category aspects are not supported in this version. '345128': domain: API_MARKETING category: REQUEST description: The minimum discount rules required for volume discount promotions are {numOfDiscountRules} '345129': domain: API_MARKETING category: REQUEST description: The 'discountRules.ruleOrder' is missing or invalid for one of the discount rules for volume discount promotions. see the documentation for this call. '345130': domain: API_MARKETING category: REQUEST description: You can include up to a maximum of {numOfDiscountRules} discount rules in a volume discount promotion. '345131': domain: API_MARKETING category: REQUEST description: Each 'minQuantity' value should be one greater than the 'minQuantity' value of the previous discount rule. '345132': domain: API_MARKETING category: REQUEST description: The discount value is invalid for one of the discount rules for volume discount promotions. see the documentation for this call. '345133': domain: API_MARKETING category: REQUEST description: Each 'percentageOffOrder' or 'amountOffOrder' value should be greater than the 'percentageOffOrder' or 'amountOffOrder' value of the previous discount rule for volume discount promotions. '345134': domain: API_MARKETING category: REQUEST description: This promotionType is currently not supported. For help, see the documentation for this call. '345135': domain: API_MARKETING category: REQUEST description: You cannot update the promotion type for a promotion. '345136': domain: API_MARKETING category: REQUEST description: The 'discountBenefit' specified is not supported for this promotion Type. For help, see the documentation for this call. '345137': domain: API_MARKETING category: REQUEST description: The 'couponCode' value is invalid. For help, see the documentation for this call. '345138': domain: API_MARKETING category: REQUEST description: You cannot update the 'couponCode' for an active or paused promotion. '345139': domain: API_MARKETING category: REQUEST description: The 'couponType' data is invalid. For help, see the documentation for this call. '345140': domain: API_MARKETING category: REQUEST description: You cannot update the 'couponType' for an active or paused promotion. '345141': domain: API_MARKETING category: REQUEST description: The 'maxCouponRedemptionPerUser' value is invalid. For help, see the documentation for this call. '345142': domain: API_MARKETING category: REQUEST description: You cannot update the 'maxCouponRedemptionPerUser' for an active or paused promotion. '345143': domain: API_MARKETING category: REQUEST description: | The 'maxDiscountAmount' value is invalid. For help, see the documentation for this call. '345144': domain: API_MARKETING category: REQUEST description: You cannot update the 'maxDiscountAmount' for an active or paused promotion. '345145': domain: API_MARKETING category: REQUEST description: You cannot apply a 'budget' to an active or paused promotion. For help, see the documentation for this call. '345146': domain: API_MARKETING category: REQUEST description: The 'budget' value is invalid. For help, see the documentation for this call. '345147': domain: API_MARKETING category: REQUEST description: The 'budget' value cannot be decreased. For help, see the documentation for this call. '345148': domain: API_MARKETING category: REQUEST description: A coupon with this 'couponCode' already exists. Please try a different 'couponCode'. '345149': domain: API_MARKETING category: REQUEST description: The 'currency' for 'maxDiscountAmount' and 'budget' has to be same. For help, see the documentation for this call. '345150': domain: API_MARKETING category: REQUEST description: '''promotionType'' CODED_COUPON is currently not supported for this Marketplace ID. For help, see the documentation for this call.' '345151': domain: API_MARKETING category: REQUEST description: The 'discountBenefit' value cannot exceed the 'maxDiscountAmount' value. '404': description: Not Found '409': description: Business Error x-response-codes: errors: '38243': domain: API_MARKETING category: BUSINESS description: The 'minQuantity' value is invalid. This value must be an integer. '38244': domain: API_MARKETING category: BUSINESS description: The 'forEachQuantity' value is invalid. This value must be an integer. '38245': domain: API_MARKETING category: BUSINESS description: The 'minAmount' value is invalid. For help, see the documentation for this call. '38246': domain: API_MARKETING category: BUSINESS description: The 'forEachAmount' value is invalid. For help, see the documentation for this call. '38247': domain: API_MARKETING category: BUSINESS description: The 'numberOfDiscountedItems' value is invalid. This value must be an integer. '38248': domain: API_MARKETING category: BUSINESS description: The 'percentOffItem' value is invalid. For help, see the documentation for this call. '38249': domain: API_MARKETING category: BUSINESS description: The 'percentOffOrder' 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. '38251': domain: API_MARKETING category: BUSINESS description: The 'amountOffOrder' value is invalid. For help, see the documentation for this call. '38266': domain: API_MARKETING category: BUSINESS description: The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification.maxAmount' value. '38268': domain: API_MARKETING category: BUSINESS description: The 'discountBenefit' value cannot exceed {maxDiscPercent}% of the 'discountSpecification'. '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 delete: tags: - item_promotion description: This method deletes the threshold promotion specified by the promotion_id path parameter. Call getPromotions to retrieve the IDs of a seller's promotions.

You can delete any promotion with the exception of those that are currently active (RUNNING). To end a running threshold promotion, call updateItemPromotion and adjust the endDate field as appropriate. operationId: deleteItemPromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the promotion you want to delete plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

' operationId: getListingSet parameters: - name: limit in: query description: Specifies the maximum number of promotions returned on a page from the result set.

Default: 200
Maximum: 200 required: false schema: type: string - name: offset in: query description: Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

Example:
   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)

Valid values: For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField required: false schema: type: string - name: status in: query description: This query parameter applies only to markdown promotions. It filters the response based on the indicated status of the promotion.

Note: Currently, the only supported value for this parameter is 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.

Default: 200
Maximum: 200 required: false schema: type: string - name: marketplace_id in: query description: This parameter specifies eBay marketplace ID of the site where the promotion is hosted.

See MarketplaceIdEnum for supported Marketplace ID values. required: true schema: type: string - name: offset in: query description: Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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.

See PromotionStatusEnum for supported values.

Maximum number of input values: 1 required: false schema: type: string - name: promotion_type in: query description: This parameter specifies the campaign promotion type by which you want to filter the results.

See PromotionTypeEnum for supported values. required: false schema: type: string - name: q in: query description: A string consisting of one or more keywords. eBay filters the response by returning only the promotions that contain the supplied keywords in the promotion title.

Example: "iPhone" or "Harry Potter."

Commas that separate keywords are ignored. For example, a keyword string of "iPhone, iPad" equals "iPhone iPad", and each results in a response that contains promotions with both "iPhone" and "iPad" in the title. required: false schema: type: string - name: sort in: query description: Specifies the order for how to sort the response. If you precede the supplied value with a dash, the response is sorted in reverse order.

Example:
   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)

Valid values: For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/marketing/types/csb:SortField required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PromotionsPagedCollection' '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. '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. '38240': domain: API_MARKETING category: REQUEST description: Invalid input for the 'promotionStatus' field. For help, see the documentation for this call. '345141': domain: API_MARKETING category: REQUEST description: Invalid input for the 'promotionType' field. 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.readonly - https://api.ebay.com/oauth/api_scope/sell.marketing /promotion/{promotion_id}/pause: post: tags: - promotion description: This method pauses a currently-active (RUNNING) threshold promotion and changes the state of the promotion from 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.

Pass the ID of the promotion you want to pause using the promotion_id path parameter. Call getPromotions to retrieve the IDs of the seller's promotions.

Note: You can only pause threshold promotions (you cannot pause markdown promotions). operationId: pausePromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the active promotion being paused plus the marketplace ID on which the promotion is hosted. Concatenate the two values by separating them with an "at sign" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

Pass the ID of the promotion you want to resume using the promotion_id path parameter. Call getPromotions to retrieve the IDs of the seller's promotions. operationId: resumePromotion parameters: - name: promotion_id in: path description: This path parameter takes a concatenation of the ID of the paused promotion being resumed 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" (@).

The ID of the promotion (promotionId) is a unique eBay-assigned value that's generated when the promotion is created. The Marketplace ID is the ENUM value of eBay marketplace where the promotion is hosted.

Use the getPromotions method to retrieve promotion Ids. See MarketplaceIdEnum for supported Marketplace ID values.

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

Specify the eBay marketplace for which you want the report run using the marketplace_id query parameter. Supply additional query parameters to control the report as needed. operationId: getPromotionReports parameters: - name: limit in: query description: Specifies the maximum number of promotions returned on a page from the result set.

Default: 200
Maximum: 200 required: false schema: type: string - name: marketplace_id in: query description: This parameter specifies the eBay marketplace ID of the site for which you want the promotions report.

See MarketplaceIdEnum for supported Marketplace ID values. required: true schema: type: string - name: offset in: query description: Specifies the number of promotions to skip in the result set before returning the first promotion in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 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.

See PromotionStatusEnum for supported values.

Maximum number of input values: 1 required: false schema: type: string - name: promotion_type in: query description: This parameter specifies the campaign promotion type by which you want to filter the results.

See PromotionTypeEnum for supported values. required: false schema: type: string - name: q in: query description: A string consisting of one or more keywords. eBay filters the response by returning only the promotions that contain the supplied keywords in the promotion title.

Example: "iPhone" or "Harry Potter."

Commas that separate keywords are ignored. For example, a keyword string of "iPhone, iPad" equals "iPhone iPad", and each results in a response that contains promotions with both "iPhone" and "iPad" in the title. required: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PromotionsReportPagedCollection' '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. '38211': domain: API_MARKETING category: REQUEST description: The offset value must be an integer value greater than or equal to zero. '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. '38240': domain: API_MARKETING category: REQUEST description: Invalid input for the 'promotionStatus' field. For help, see the documentation for this call. '345141': domain: API_MARKETING category: REQUEST description: Invalid input for the 'promotionType' field. 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.readonly - https://api.ebay.com/oauth/api_scope/sell.marketing /promotion_summary_report: get: tags: - promotion_summary_report description: This method generates a report that summarizes the seller's promotions for the specified eBay marketplace. The report returns information on RUNNING, PAUSED, and ENDED promotions (deleted reports are not returned) and summarizes the seller's campaign performance for all promotions on a given site.

For information about summary reports, see Reading the item promotion Summary report. operationId: getPromotionSummaryReport parameters: - name: marketplace_id in: query description: This parameter specifies the eBay marketplace ID of the site for which you want a promotions summary report.

See MarketplaceIdEnum for supported Marketplace ID values. required: true schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/SummaryReportResponse' '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. '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 /email_campaign: get: tags: - email_campaign description: This method retrieves a list of email campaigns from a seller's eBay store.

Users can filter the results by email campaign type, email campaign status, and marketplace ID using the q query parameter. operationId: getEmailCampaigns parameters: - name: limit in: query description: 'The maximum number of email campaigns returned in a page.

Min value: 1

Max value: 200' required: false schema: type: string - name: offset in: query description: 'The number of results to skip in a pagination query. This value cannot be less than zero.

Default value: 0' required: false schema: type: string - name: q in: query description: This field contains filter criteria for the results returned. Filter by email campaign type, email campaign status, and marketplace ID.

For example, setting q=campaignType:WELCOME,ITEM_SHOWCASE will return only Welcome and Item Showcase email campaigns.

Note: At least one 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.

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

A successful createEmailCampaign request returns the emailCampaignId assigned to the new email campaign.

The fields emailCampaignType, audienceCodes, itemSelectMode, subject, and personalizedMessage are required for all email campaign types.

Specific email campaign types have required values for additional fields. For more information on the email campaign types, see the Store Email Campaigns section of the Selling Integration Guide. ' operationId: createEmailCampaign parameters: - name: X-EBAY-C-MARKETPLACE-ID in: header description: The eBay marketplace that the email campaign interfaces with.

eBay marketplaces correspond to geographical regions or large submarkets of regions. For example, EBAY-US corresponds to the United States market.

See MarketplaceIdEnum for supported values. 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: Create a new email campaign request. content: application/json: schema: description: Create a new email campaign request. $ref: '#/components/schemas/CreateEmailCampaignRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateEmailCampaignResponse' '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. '35201': domain: STORE_CRM category: REQUEST description: '''marketplaceId'' value is not supported. For the valid values, see the documentation for this call.' '35202': domain: STORE_CRM category: REQUEST description: '''emailCampaignType'' value is not supported. For the valid values, see the documentation for this call.' '35203': domain: STORE_CRM category: REQUEST description: '''audiences'' is required for this call.' '35204': domain: STORE_CRM category: REQUEST description: '''subject'' is required for this call.' '35205': domain: STORE_CRM category: REQUEST description: '''personalizedMessage'' is required for this call.' '35206': domain: STORE_CRM category: REQUEST description: '''subject'' length is too long. For maximum limits, see the documentation for this call.' '35207': domain: STORE_CRM category: REQUEST description: '''audiences'' value is not suitable for current email campaign type.' '35208': domain: STORE_CRM category: REQUEST description: '''itemIds'' is required for this call.' '35209': domain: STORE_CRM category: REQUEST description: For 'WELCOME' type campaign, 'itemIds' should be empty. '35210': domain: STORE_CRM category: REQUEST description: The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call. '35211': domain: STORE_CRM category: REQUEST description: No eligible items for current campaign. '35212': domain: STORE_CRM category: REQUEST description: '''promotionId'' is required for this call.' '35213': domain: STORE_CRM category: REQUEST description: '''promotionId'' is invalid, promotion may be inactive or non-exist.' '35214': domain: STORE_CRM category: REQUEST description: '''scheduleDate'' is not required for this call.' '35215': domain: STORE_CRM category: REQUEST description: '''scheduleDate'' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm.sssZ) string.' '35216': domain: STORE_CRM category: REQUEST description: Only one 'WELCOME' type email campaign is allowed for one marketplace. '35217': domain: STORE_CRM category: REQUEST description: Only one automated promotion email campaign is allowed for one campaign type per marketplace id. '35218': domain: STORE_CRM category: REQUEST description: '''personalizedMessage'' length is too long. For maximum limits, see the documentation for this call.' '35219': domain: STORE_CRM category: REQUEST description: The email campaign schedule date {scheduleDate} must be in the future. '35220': domain: STORE_CRM category: REQUEST description: '''itemIds'' contains ineligible item id, please check the item list' '35221': domain: STORE_CRM category: REQUEST description: '''itemSelectMode'' is invalid for this campaign, please see the documentation for this call.' '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 /email_campaign/{email_campaign_id}: get: tags: - email_campaign description: This method returns the details of a single email campaign specified by the email_campaign_id path parameter.

Call getEmailCampaigns to retrieve a list of all email campaigns from a seller's eBay store. operationId: getEmailCampaign parameters: - name: email_campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier of the email campaign being retrieved.

Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetEmailCampaignResponse' '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. '35501': domain: STORE_CRM category: REQUEST description: No email campaign found for email campaign ID {email_campaign_id}. '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 put: tags: - email_campaign description: 'This method lets users update an existing email campaign. Pass the emailCampaignId in the request URL and specify the changes to field values in the request payload.

Note: You can only update the custom fields of an email campaign. Fixed values, such as the emailCampaignType, cannot be changed. For full specifications of fixed values for each email campaign type, see the createEmailCampaign method documentation.' operationId: updateEmailCampaign parameters: - name: email_campaign_id in: path description: This path parameter specifies the unique eBay assigned identifier for the email campaign being updated.

Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller. 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: update email campaign request content: application/json: schema: description: update email campaign request $ref: '#/components/schemas/UpdateCampaignRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UpdateEmailCampaignResponse' '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. '35801': domain: STORE_CRM category: REQUEST description: '''audiences'' is required for this call.' '35802': domain: STORE_CRM category: REQUEST description: No email campaign found for email campaign ID {email_campaign_id}. '35803': domain: STORE_CRM category: REQUEST description: '''subject'' is required for this call.' '35804': domain: STORE_CRM category: REQUEST description: '''personalizedMessage'' is required for this call.' '35805': domain: STORE_CRM category: REQUEST description: '''subject'' length is too long. For maximum limits, see the documentation for this call.' '35806': domain: STORE_CRM category: REQUEST description: '''audiences'' value is not suitable for current email campaign type.' '35807': domain: STORE_CRM category: REQUEST description: '''itemIds'' is required for this call.' '35808': domain: STORE_CRM category: REQUEST description: For 'WELCOME' type campaign, 'itemIds' should be empty. '35809': domain: STORE_CRM category: REQUEST description: The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call. '35810': domain: STORE_CRM category: REQUEST description: No eligible items for current campaign. '35811': domain: STORE_CRM category: REQUEST description: '''promotionId'' is required for this call.' '35812': domain: STORE_CRM category: REQUEST description: '''promotionId'' is invalid, promotion may be inactive or non-exist.' '35813': domain: STORE_CRM category: REQUEST description: '''scheduleDate'' is not required for this call.' '35814': domain: STORE_CRM category: REQUEST description: '''scheduleDate'' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string.' '35815': domain: STORE_CRM category: REQUEST description: '''email_campaign_id'' is not eligible for editing.' '35816': domain: STORE_CRM category: REQUEST description: '''personalizedMessage'' length is too long. For maximum limits, see the documentation for this call.' '35817': domain: STORE_CRM category: REQUEST description: The email campaign schedule date {scheduleDate} must be in the future. '35818': domain: STORE_CRM category: REQUEST description: '''itemIds'' contains ineligible item id, please check the item list' '35819': domain: STORE_CRM category: REQUEST description: '''itemSelectMode'' is invalid for this campaign, please see the documentation for this call.' '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 delete: tags: - email_campaign description: This method deletes the email campaign specified by the email_campaign_id path parameter.

Call getEmailCampaigns to retrieve all of the seller's email campaigns. Use the email_campaign_id of the desired email campaign in the response as the path parameter for this request. operationId: deleteEmailCampaign parameters: - name: email_campaign_id in: path description: This path parameter specifies the unique eBay-assigned identifier for the email campaign being deleted.

You can retrieve the email campaign IDs for a specified seller using the getEmailCampaigns method. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DeleteEmailCampaignResponse' '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. '35401': domain: STORE_CRM category: REQUEST description: No email campaign found for email campaign ID {email_campaign_id}. '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 /email_campaign/audience: get: tags: - email_campaign description: This method retrieves all available email newsletter audiences for the email campaign type specified by the emailCampaignType path parameter.

Use the optional limit and offset path parameters to paginate the results and to control which records are returned, respectively. operationId: getAudiences parameters: - name: emailCampaignType in: query description: The email campaign type to search against.

See CampaignTypeEnum for the full list of available email campaign types and associated enum values. required: true schema: type: string - name: limit in: query description: 'The maximum number of audience groups returned per page in the results set.

Min value: 1

Max value: 200

Default value: 100' required: false schema: type: string - name: offset in: query description: 'The number of results to skip in a pagination query. This value cannot be less than 0.

Default value: 0' required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetEmailCampaignAudiencesResponse' '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. '35101': 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. '35102': domain: STORE_CRM category: REQUEST description: The paginated query offset {offset} value is mossing or invalid. The value cannot be less than zero. '35103': domain: STORE_CRM category: REQUEST description: The email campaign type {emailCampaignType} is not supported. For the valid value, please see the documentation for this call. '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 /email_campaign/{email_campaign_id}/email_preview: get: tags: - email_campaign description: This method returns a preview of the email sent by the email campaign indicated by the email_campaign_id path parameter.

Call getEmailCampaigns to obtain a list of email campaigns. Use the emailCampaignId value of the desired email campaign as the email_campaign_id path parameter value.

If this call is executed successfully, the response returns a content field that contains the raw HTML code of the email campaign that can then be rendered anywhere.

Note: The eBay listings in the email are sorted according to the email campaign sort criteria. The individual listings can change over time, as well.

The result of the email preview call can be treated as a snapshot of the email campaign taken at the date and time of the renderDate value found in the results of the call.
operationId: getEmailPreview parameters: - name: email_campaign_id in: path description: This path parameter specifies the unique eBay assigned identifier for the email campaign associated with the preview being retrieved.

Use the getEmailCampaigns method to retrieve a list of email campaign IDs for a seller. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetEmailPreviewResponse' '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. '35601': domain: STORE_CRM category: REQUEST description: No email campaign found for email campaign ID {email_campaign_id}. '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 /email_campaign/report: get: tags: - email_campaign description: 'This method returns the seller''s email campaign performance report for a time period specified by the startDate and endDate path parameters. The maximum date range for a report retrieved by this method is one year.

Note: The startDate and endDate must be given in UTC format, as shown in the following example:
sell/marketing/v1/email_campaign/report?startDate=2022-11-01T19:09:02.768Z&endDate=2022-12-28T19:09:02.768Z

The email report returns a list of metrics, such as the number of times an email report has been opened and resulted in clicks.' operationId: getEmailReport parameters: - name: endDate in: query description: The end date for the report, given in UTC format. The maximum date range for a report retrieved by this method is one year. required: true schema: type: string - name: startDate in: query description: The start date for the report, given in UTC format. The maximum date range for a report retrieved by this method is one year. required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetEmailReportResponse' '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. '35701': domain: STORE_CRM category: REQUEST description: '''startDate'' value is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string.' '35702': domain: STORE_CRM category: REQUEST description: '''endDate'' value is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm:sssZ) string.' '35703': domain: STORE_CRM category: REQUEST description: The query start date {startDate} cannot be later than query end date {endDate}. '35704': domain: STORE_CRM category: REQUEST description: The time interval between start date and end date exceeds maximum limit. For maximum limits, please see the documentation for this call. '35705': domain: STORE_CRM category: REQUEST description: '''currency'' value is not supported. For the valid values, see the documentation for this call.' '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 components: schemas: Ad: 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. This ID is created after a successful createAdGroup call, and all ad groups must be associated with a CPC campaign. adId: type: string description: A unique eBay-assigned ID that is generated when the ad is created. adStatus: type: string description: The current status of the CPC ad.

Valid Values:Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. For implementation help, refer to eBay API documentation alerts: type: array description: An array containing alert messages for the ad. items: $ref: '#/components/schemas/Alert' bidPercentage: type: string description: 'The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

The bidPercentage is a single precision value that is guided by the following rules: This is default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.

If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Note:This field will always be returned for campaigns that use the Cost Per Sale (CPS) funding model. It will not be returned for campaigns that use the Cost Per Click (CPC) funding model.

Note: This field has a minimum value of 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 be INVENTORY_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.

Valid Values: For implementation help, refer to eBay API documentation defaultBid: description: 'A bid amount that applies to all of the keywords in an ad group that do not have individual bids. For all keywords without individual bids, the default bid is the amount that the seller will pay per click for the listings in the ad group in the promoted listings campaign.

Valid Values: 0.5, 0.75' $ref: '#/components/schemas/Amount' name: type: string description: The seller-defined name of the ad group. description: A container for the details of an existing ad group.

An ad group can be added to a campaign that uses the Cost Per Click (CPC) funding model. A campaign may have multiple ad groups. All listings that are promoted in the campaign are included in the ad group.

Note: This type only applies to the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model. AdGroupPagedCollectionResponse: type: object properties: adGroups: type: array description: The details of existing ad groups, such as the name, ID, and status of the ad groups. items: $ref: '#/components/schemas/AdGroup' href: type: string description: The URI of the current page of results from the result set. limit: type: integer description: The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter. format: int32 next: type: string description: The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set. offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Default: 0


Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.' format: int32 prev: type: string description: The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results. total: type: integer description: 'The total number of items retrieved in the result set.

Note: If no items are found, this field is returned with a value of 0.' format: int32 description: A container for the details of a paged collection of ad groups.

Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. AdIds: type: object properties: adIds: type: array description: A list of ad IDs. Only one ad can be deleted per operation and only one adId value will be returned. items: type: string description: This type is a container for a list of ad IDs. AdPagedCollectionResponse: type: object properties: ads: type: array description: The list of ads that matched the request criteria. items: $ref: '#/components/schemas/Ad' 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.

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.

' format: int32 prev: type: string description: 'The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.

Max length: 2048' total: type: integer description: The total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 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.

Valid Value: 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.

Valid Values: For implementation help, refer to eBay API documentation value: type: string description: The data provided for the specified metric.

Note: All metric data is compiled for the marketplace associated with the specified campaign ID. description: A type that defines the data produced for additional information about suggested keywords. Ads: type: object properties: ads: type: array description: A list of ad IDs. An ad ID is generated for each successfully created ad. items: $ref: '#/components/schemas/Ad' description: This type defines the container for an array of ads. Alert: type: object properties: alertType: type: string description: The type of alert message. For example, an invalid bid percentage. For implementation help, refer to eBay API documentation details: type: array description: A description of the alert including dimensions and aspects. items: $ref: '#/components/schemas/AlertDetails' description: A type that contains the alert message fields for the ad. AlertDetails: type: object properties: dimension: description: The dimension information of the alert including keys and values. $ref: '#/components/schemas/AlertDimension' aspect: description: The aspect information of the alert including keys and values. $ref: '#/components/schemas/Aspect' description: A type that contains the alert detail fields. AlertDimension: type: object properties: key: type: string description: The key field of the applied dimension. For example, the marketplace Id. For implementation help, refer to eBay API documentation value: type: string description: The value field of the applied dimension. For example, if the key is a 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.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD For implementation help, refer to eBay API documentation value: type: string description: The monetary amount in the specified currency.

Required in the amount type. description: A complex type that describes the value of a monetary amount as represented by a global currency. Aspect: type: object properties: key: type: string description: The type of the aspect. For example, 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. BidPreference: type: object properties: maxCpc: description: The maximum amount for which the eBay suggested bid can be adjusted. This value represents the most a seller is willing to pay for each click on their ad. The adjusted bid will never exceed this amount.

This field is required for smart targeting campaigns.

Note: The maximum cost-per-click has a minimum value of 0.02 and a maximum value of 100. $ref: '#/components/schemas/MaxCpc' description: This type indicates the bidding preferences of a Smart Targeting campaign.

Note: This type is only supported for CPC funding model campaigns with on-site channels. 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.

Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model. BudgetRecommendationResponse: type: object properties: budget: description: The allocated daily budget for the Cost Per Click (CPC) Promoted Listings campaign. $ref: '#/components/schemas/CampaignBudget' campaignId: type: string description: The unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created. channels: type: array description: The channel for the campaign. This value indicates whether the campaign is an Onsite or Offsite advertising campaign.

Valid Values: items: type: string description: ' For implementation help, refer to eBay API documentation' description: This type indicates the suggested daily keyword budget for an Offsite Ads campaign. BudgetRequest: type: object properties: amount: description: The allocated budget amount for a CPC Promoted Listings campaign. Both the currency and value must be specified. $ref: '#/components/schemas/Amount' description: A container for the budget details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model.

Note: This container will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model. BulkAdResponse: type: object properties: responses: type: array description: This array displays the list of ads that were successfully created. For any ads that were not created successfully, the errors array may provide more detail about why creation of one or more ads failed. items: $ref: '#/components/schemas/AdResponse' description: This type defines the fields for the create ads in bulk response. BulkAdUpdateResponse: type: object properties: responses: type: array description: A set of ad listings processed by the call. items: $ref: '#/components/schemas/AdUpdateResponse' description: A type that defines the fields for updated ads in the bulk response. BulkAdUpdateStatusByListingIdResponse: type: object properties: responses: type: array description: An array of processed ad listings in bulk. items: $ref: '#/components/schemas/AdUpdateStatusByListingIdResponse' description: A type that defines the fields for the updated ad status in the bulk response. BulkAdUpdateStatusResponse: type: object properties: responses: type: array description: An array of processed ad listings in bulk. items: $ref: '#/components/schemas/AdUpdateStatusResponse' description: A type that defines the fields for the updated ad status in the bulk response. BulkCreateAdRequest: type: object properties: requests: type: array description: 'An array of listing IDs and their associated bid percentages, which the request uses to create ads in bulk. 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).

Maximum: 500 IDs per call' items: $ref: '#/components/schemas/CreateAdRequest' description: This type defines the fields for the create ads in bulk by listing IDs. BulkCreateAdsByInventoryReferenceRequest: type: object properties: requests: type: array description: A list of inventory reference ID and inventory reference type pairs, and the bid percentage, which the call uses to create ads in bulk. items: $ref: '#/components/schemas/CreateAdsByInventoryReferenceRequest' description: This type defines the fields used to create ads in bulk by inventory reference IDs. BulkCreateAdsByInventoryReferenceResponse: type: object properties: responses: type: array description: This array displays the list of ads that were successfully created. For any ads that were not created successfully, the errors array may provide more detail about why creation of one or more ads failed. items: $ref: '#/components/schemas/CreateAdsByInventoryReferenceResponse' description: This type defines the response fields used by the bulkCreateAdsByInventoryReference method. BulkCreateKeywordRequest: type: object properties: requests: type: array description: This array is used to pass in multiple keywords for one or more ad groups that belong to a campaign that uses the Cost Per Click (CPC) funding model. Up to {max value} keywords can be created with one call. items: $ref: '#/components/schemas/CreateKeywordRequest' description: A type that contains the fields for the bulk request to create keywords. BulkCreateKeywordResponse: type: object properties: responses: type: array description: A list of keywords that have been processed by the request. items: $ref: '#/components/schemas/KeywordResponse' description: A type that contains the response fields for the bulk request to create keywords. BulkCreateNegativeKeywordRequest: type: object properties: requests: type: array description: This array is used to pass in multiple negative keywords for one or more ad groups that belong to a campaign that uses the Cost Per Click (CPC) funding model. items: $ref: '#/components/schemas/CreateNegativeKeywordRequest' description: A type that contains the fields for the bulk request to create negative keywords. BulkCreateNegativeKeywordResponse: type: object properties: responses: type: array description: A list of negative keywords that have been processed by the request. items: $ref: '#/components/schemas/NegativeKeywordResponse' description: A type that contains the response fields for the bulk request to create negative keywords. BulkDeleteAdRequest: type: object properties: requests: type: array description: An array of the listing IDs that identify the ads to remove. items: $ref: '#/components/schemas/DeleteAdRequest' description: This type defines the fields that the call uses to remove ads in bulk. BulkDeleteAdResponse: type: object properties: responses: type: array description: An array of the ads that were deleted by the bulkDeleteAdsByListingId request, including information associated with each individual delete request. items: $ref: '#/components/schemas/DeleteAdResponse' description: This type defines a container that lists the ads that bulkDeleteAdsByListingId deleted. BulkDeleteAdsByInventoryReferenceRequest: type: object properties: requests: type: array description: A list of inventory referenceID and inventory reference type pairs that specify the set of ads to remove in bulk. items: $ref: '#/components/schemas/DeleteAdsByInventoryReferenceRequest' description: This type defines the request fields that bulkDeleteAdsByInventoryReference uses to delete ads in bulk. BulkDeleteAdsByInventoryReferenceResponse: type: object properties: responses: type: array description: An array of the ads that were deleted by the bulkDeleteAdsByInventoryReference request, including information associated with each individual delete request. items: $ref: '#/components/schemas/DeleteAdsByInventoryReferenceResponse' description: This type defines a container that lists the ads that bulkDeleteAdsByInventoryReference deleted. BulkUpdateAdStatusByListingIdRequest: type: object properties: requests: type: array description: An array of listing IDs and bid percentages. items: $ref: '#/components/schemas/UpdateAdStatusByListingIdRequest' description: A type that defines the fields for the BulkUpdateAdStatusByListingId request. BulkUpdateAdStatusRequest: type: object properties: requests: type: array description: An array of listing IDs and bid percentages. items: $ref: '#/components/schemas/UpdateAdStatusRequest' description: A type that defines the fields for the BulkUpdateAdStatus request. BulkUpdateAdsByInventoryReferenceResponse: type: object properties: responses: type: array description: A list of inventory references that were processed from the request. items: $ref: '#/components/schemas/UpdateAdsByInventoryReferenceResponse' description: A type that defines the fields for the BulkUpdateAdStatusByInventoryReference response. BulkUpdateKeywordRequest: type: object properties: requests: type: array description: Use this array to update the bid values and/or statuses of one or more existing keywords. items: $ref: '#/components/schemas/UpdateKeywordByKeywordIdRequest' description: A type that defines the fields for the BulkUpdateKeyword request. BulkUpdateKeywordResponse: type: object properties: responses: type: array description: A list of keywords that have been processed from the bulk request. items: $ref: '#/components/schemas/UpdateKeywordResponse' description: A type that defines the fields for the BulkUpdateKeyword response. BulkUpdateNegativeKeywordRequest: type: object properties: requests: type: array description: An array to update the statuses of one or more existing negative keywords. items: $ref: '#/components/schemas/UpdateNegativeKeywordIdRequest' description: A type that defines the fields for the BulkUpdateNegativeKeyword request. BulkUpdateNegativeKeywordResponse: type: object properties: responses: type: array description: A list of negative keywords that have been processed from the bulk request. items: $ref: '#/components/schemas/UpdateNegativeKeywordResponse' description: A type that defines the fields for the BulkUpdateNegativeKeyword response. Campaign: type: object properties: alerts: type: array description: This array contains alert messages for the campaign. items: $ref: '#/components/schemas/Alert' budget: description: The allocated budget for the Cost Per Click (CPC) Promoted Listings campaign.Note: This field will only be returned for campaigns using the CPC funding model; it does not apply to the Cost Per Sale (CPS) funding model. $ref: '#/components/schemas/CampaignBudget' campaignCriterion: description: The selection rules (criterion) used to select the listings for a campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign.Note: This container is only returned for rules-based campaigns using the Cost Per Sale (CPS) funding model. $ref: '#/components/schemas/CampaignCriterion' campaignId: type: string description: A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created. campaignName: type: string description: A seller-defined name for the campaign. This value must be unique for the seller.

You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.

Max length: 80 characters campaignStatus: type: string description: Indicates the status of the campaign, such as RUNNING, PAUSED, and ENDED. For implementation help, refer to eBay API documentation campaignTargetingType: type: string description: The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting ad campaign. 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.

Valid Values: 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.

Currently, the supported funding models are 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.

Required if the campaign's funding model is CPC.

This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.

When running an Offsite Ads campaign, eBay may spend more or less than the seller's daily budget to capitalize on interested buyers, but will not exceed 2x the daily budget. The average over the course of the campaign will not exceed the provided daily budget. This value is used to calculate a total monthly budget by multiplying 30.4 by the provided daily budget. Over the course of the campaign, eBay will not charge more than this total budget per month.

If a campaign ends prematurely, however, the seller may be charged up to 2x their daily budget on a daily basis, as the campaign may have not had the chance to average the budget out over time.

Valid Values: $ref: '#/components/schemas/Budget' description: A type that defines the budget details for a Cost Per Click (CPC) Promoted Listings campaign. CampaignBudgetRequest: type: object properties: daily: description: The daily budget limit for a CPC Promoted Listings campaign.

When running an Offsite Ads campaign, eBay may spend more or less than the seller's daily budget to capitalize on interested buyers, but will not exceed 2x the daily budget. The average over the course of the campaign will not exceed the provided daily budget. This value is used to calculate a total monthly budget by multiplying 30.4 by the provided daily budget. Over the course of the campaign, eBay will not charge more than this total budget per month.

If a campaign ends prematurely, however, the seller may be charged up to 2x their daily budget on a daily basis, as the campaign may have not had the chance to average the budget out over time. $ref: '#/components/schemas/BudgetRequest' description: A container for the details of a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model. CampaignCriterion: type: object properties: autoSelectFutureInventory: type: boolean description: A field used to indicate whether listings shall be automatically added to, or removed from, a Promoted Listings campaign based on the rules that have been configured for the campaign.

If set to true, eBay adds all listings matching the campaign criterion to the campaign, including any new listings created from the items in a seller's inventory.

Default: false 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.

Do not include this field if you manage your listings with Trading API/legacy model. For implementation help, refer to eBay API documentation selectionRules: type: array description: This container shows all of the rules/inclusion filters used to add listings to the campaign. For information on using the contained fields, see Promoted Listing campaigns. items: $ref: '#/components/schemas/SelectionRule' description: This type defines the fields for specifying the criterion (selection rule) settings of an ad campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the newly created campaign. CampaignDTO: type: object properties: audiences: type: array description: The audiences that the email campaign is being sent to. See AudienceTypeEnum for a list of audience types. items: $ref: '#/components/schemas/CampaignAudience' creationDate: type: string description: The date and time that the email campaign was created, given in UTC format. emailCampaignId: type: string description: The unique eBay identifier for the email campaign assigned automatically when the email campaign is created. emailCampaignStatus: type: string description: The email campaign status. See EmailCampaignStatusEnum for information on statuses. For implementation help, refer to eBay API documentation emailCampaignType: type: string description: The email campaign type. See CampaignTypeEnum for definitions of email campaign types. For implementation help, refer to eBay API documentation marketplaceId: type: string description: The eBay marketplace where the email campaign is active. modificationDate: type: string description: The date and time the email campaign was last modified, given in UTC format. scheduleDate: type: string description: The date and time that the email campaign newsletter is scheduled to send, given in UTC format. scheduleDateType: type: string description: The schedule type used for sending the email campaign. See ScheduleDateTypeEnum for available schedule types. For implementation help, refer to eBay API documentation sentDate: type: string description: The date and time that the email campaign was last sent, given in UTC format. subject: type: string description: The email campaign subject line.. description: email campaign instance body CampaignPagedCollectionResponse: type: object properties: campaigns: type: array description: This array contains all of the seller's campaign that match the request criteria. items: $ref: '#/components/schemas/Campaign' href: type: string description: The URI of the current page of results from the result set. limit: type: integer description: The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter. format: int32 next: type: string description: 'The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.

Max length: 2048' offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

' format: int32 prev: type: string description: 'The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.

Max length: 2048' total: type: integer description: The total number of campaigns retrieved in the result set.

If no campaigns are found, this field is returned with a value of 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.

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

The code must be from 8-15 alphanumeric characters and can contain no more than two dashes ( - ).

This is required when the promotion type is CODED_COUPON. couponType: type: string description: This indicates the type of Coded Coupon promotion, and is required when the promotion type is CODED_COUPON.

Supported types: For implementation help, refer to eBay API documentation maxCouponRedemptionPerUser: type: integer description: This sets the limit on the number of times a buyer can use this coupon. The range of values is 1-10. If no value is provided, a buyer can use the coupon an unlimited number of times. format: int32 description: This container defines a coded coupon promotion. It is required if the promotion type is CODED_COUPON. CreateAdGroupRequest: type: object properties: defaultBid: description: A bid amount that applies to all of the keywords in an ad group that do not have individual bids. $ref: '#/components/schemas/Amount' name: type: string description: The seller-defined name of the ad group. description: A type that defines the fields for the CreateAdGroup request. CreateAdRequest: type: object properties: adGroupId: type: string description: A unique eBay-assigned identifier for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.

Use the getAdGroups method to retrieve the ad group IDs for a seller.

Note: This field is required for manual targeting campaign using the Cost Per Click (CPC) funding model. 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.

Required if the campaign''s funding model is Cost Per Sale (CPS).

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

The bidPercentage is a single precision value that is guided by the following rules:
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Note: This field has a minimum value of 2.0 and a maximum value of 100.0.' 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.

Required if the campaign''s funding model is Cost Per Sale (CPS).

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

The bidPercentage is a single precision value that is guided by the following rules:
If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Note: This field has a minimum value of 2.0 and a maximum value of 100.0.' inventoryReferenceId: type: string description: The unique identifier of a single-item listing or a multi-variation listing.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API. inventoryReferenceType: type: string description: This enumerated value indicates the type of item the inventoryReferenceId references.

The item can be either an 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 an INVENTORY_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.

Required if the campaign funding model is CPC. $ref: '#/components/schemas/CampaignBudgetRequest' campaignCriterion: description: This container is used if the seller wishes to create one or more rules for a rules-based campaign. If you populate the campaignCriterion object in your createCampaign request, ads for the campaign are created by rule for the listings that meet the criteria you specify, and these ads are associated with the campaign to be created.

Note: Rules-based listing selection is only applicable for Promoted Listings Standard campaigns using the Cost-Per-Sale (CPS) funding model. $ref: '#/components/schemas/CampaignCriterion' campaignName: type: string description: A seller-defined name for the campaign. This value must be unique for the seller.

You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.

Max length: 80 characters campaignTargetingType: type: string description: The targeting type of the campaign. This value indicates whether the campaign is a manual targeting or smart targeting campaign.

If not value is specified, this field will default to MANUAL.

Note: This feature is only supported for on-site campaigns that use the Cost Per Click (CPC) funding model.
Valid Values:This field is required and must be set to SMART for a Smart Targeting campaign. For implementation help, refer to eBay API documentation channels: type: array description: The channel for the campaign. This value indicates whether the advertising campaign is an Onsite or Offsite.

If no value is entered, this field will default to ON_SITE. Multiple channels are not supported.

Note: Channels is only applicable for campaigns that use the Cost Per Click (CPC) funding model.
Valid Values:This field is required and must be set to 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.

To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes. items: type: string categoryId: type: string description: The unique identifier of either an eBay category or a store category.

This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.

To retrieve eBay categories, use the getCategories or Taxonomy API. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.

itemSelectMode must be set to AUTO in order to use a category ID. categoryType: 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:
Note: emailCampaignType cannot be updated once the email campaign is created. 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.

Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.

The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10

itemSelectMode must be set to MANUAL in order to use this field. items: type: string itemSelectMode: type: string description: 'Determines whether listings featured in an email campaign are selected by the seller or by eBay.

If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.

If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.

Note: itemSelectMode is always set to AUTO for WELCOME email campaigns. For implementation help, refer to eBay API documentation' personalizedMessage: type: string description: The body of the email campaign. Accepts HTML and CSS.

Max length: 1000 priceRange: description: 'This container is used if the seller wants to apply the email campaign to listings based on a price range.

The priceRange container consists of the currency, gte, and lte fields.

"gte" stands for "greater than or equal to" and "lte" stands for "less than or equal to". Either gte, lte, or both must be used.

currency is a required field if including a price range. One of the three-digit currency codes from CurrencyCodeEnum must be specified.

Note: Use this object when the itemSelectMode is set to 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.

Call getPromotions to retrieve a list of the seller's promotions. Use the promotionId from an individual PromotionDetail in the result to populate the request. promotionSelectModeEnum: type: string description: The selection mode for the promotion used if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT.

If promotionSelectModeEnum is set to 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:35Z

This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated.' sort: type: string description: The sort rule is used to display the listings featured in the email campaign.

Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array. The following sort rules are available:

The default sort rule is NEWLY_LISTED. For implementation help, refer to eBay API documentation subject: type: string description: The subject line of the email campaign.

Max length: 70 description: create email campaign request payload CreateEmailCampaignResponse: type: object properties: emailCampaignId: type: string description: The unique eBay-assigned identifier of the email campaign. It is generated automatically when the email campaign is created.

This value is returned unless there is an error. emailCampaignStatus: type: string description: The status 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 maximum bid for the keyword. Each time a listing is retrieved in search results using this keyword and clicked on, the seller will be charged, at most, this amount. Each click goes toward the daily budget set up for the CPC campaign. If the bid is not provided, then the default bid associated with the ad group is used.

Note: You can call the suggestBids method to retrieve the suggested bids for keywords. $ref: '#/components/schemas/Amount' 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).

Maximum number of characters: 100

Maximum number of words: 10 matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation description: A type that defines the fields for the CreateKeyword request. CreateNegativeKeywordRequest: 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 to which the corresponding negative keyword will be added.

Use the getAdGroups method to retrieve the ad group IDs for a seller.

Required if the negative keyword is being created at the ad group level. campaignId: type: string description: This path parameter specifies the unique eBay-assigned identifier of the ad campaign associated with the set of negative keywords being created.

Use the getCampaigns method to retrieve campaign IDs.

Required if the negative keyword is being created at the ad group level. negativeKeywordMatchType: type: string description: A field that defines the match type for the negative keyword.

Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation negativeKeywordText: type: string description: The negative keyword text. description: A type that defines the fields for the CreateNegativeKeyword request. CreateReportTask: type: object properties: additionalRecords: type: array description: A list of additional records that shall be included in the report, such as non-performing data.

Note: Additional records are only applicable to Promoted Listings Advanced (PLA) campaigns that use the Cost Per Click (CPC) funding model.
Valid Value: 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.

For Promoted Listings Standard (PLS) sellers, this field is required if the reportType is set to CAMPAIGN_PERFORMANCE_REPORT or CAMPAIGN_PERFORMANCE_SUMMARY_REPORT.

For Promoted Listings Advanced (PLA) sellers, leave this request field blank to retrieve the details for all campaigns associated with your account, or specify the campaign IDs for which you would like to retrieve the campaign-specific details.

Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details.

Maximum: 1,000 IDs (for PLA or PLS) items: type: string channels: type: array description: The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign.

If no value is entered, this field will default to ON_SITE. Multiple channels are not supported.

Note: Channels are only applicable for campaigns that use the Cost Per Click (CPC) funding model.
Valid Values:This field is required and must be set to 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.

Format the timestamp as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock with local offset.

Note: The date specified cannot be a future date.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z

Example: 2021-03-15T13:00:00-07:00 dateTo: type: string description: The date defining the end of the timespan covered by the report.

As with the dateFrom field, format the timestamp as an ISO 8601 string.

Note: The date specified cannot be a future date. Additionally, the time specified must be a later time than that specified in the dateFrom field.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z

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

items: $ref: '#/components/schemas/Dimension' fundingModels: type: array description: The funding model for the campaign that shall be included in the report.

Note: The default funding model for Promoted Listings reports is COST_PER_SALE.

Note: Multiple value support for the fundingModels array has been deprecated. See API Deprecation Status for information.

Valid Values:Required if the campaign funding model is Cost Per Click (CPC). items: type: string description: ' For implementation help, refer to eBay API documentation' inventoryReferences: type: array description: 'You can use this field to supply an array of items to include in the report if you manage your inventory with the Inventory API.

This field is mutually exclusive with the listingIds field; if you populate this field, do not populate the listingIds field.

An inventory reference identifies an item in your inventory using a pair of values, where the inventoryReferenceId can be either a seller-defined SKU value or an inventoryItemGroupKey, where an inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing).

Couple the inventoryReferenceId with an inventoryReferenceType identifier to fully identify an item in your inventory.

Maximum: 500 items

Required if you do not supply an array of listingId values or if you set reportType to 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.

Important: This field is mutually exclusive with the inventoryReferences field; if you populate this field, do not populate the inventoryReferences field.
For Promoted Listings Standard (PLS) sellers, this field is required if you do not supply an array of inventoryReferences values or if you set the reportType to LISTING_PERFORMANCE_REPORT.

For Promoted Listings Advanced (PLA) sellers, leave this field blank to retrieve the details for all listings associated with the specified campaign IDs (or all campaigns associated with your account, if no campaign IDs are specified), or specify the listing IDs for which you would like to retrieve the listing-specific details.

Note: There is a maximum data limit that cannot be exceeded when generating reports. If this threshold is exceeded, the report will fail. Refer to Promoted Listings reporting in the Selling Integration Guide for details.

Maximum: 500 listings items: type: string marketplaceId: type: string description: The unique identifier for the eBay marketplace on which the report is based. For implementation help, refer to eBay API documentation metricKeys: type: array description: 'The list of metrics to be included in the 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 is TSV_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: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending.

Maximum: 1 For implementation help, refer to eBay API documentation description: This type defines the rules that govern the generation of a report task and the criteria that's used to create the report. The report-generation rules include the starting and ending dates for the report. Report-task criteria includes the report dimensions, metrics, listings covered in the report, and so on. For information on the required and optional fields for each report type, see Promoted Listings reporting. DeleteAdRequest: type: object properties: listingId: type: string description: A unique eBay-assigned identifier for a listing that is generated when the listing is created.

Note: This request accepts both listing IDs, as generated by the Inventory API, and an item IDs, as used in the eBay Traditional API set (e.g., the Trading and Finding APIs).

description: This type defines the fields used in a delete-ad request. DeleteAdResponse: type: object 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.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API. inventoryReferenceType: type: string description: This enumerated value indicates the type of item the inventoryReferenceId references.

The item can be either an 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 be listing_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.

For threshold promotions, where the buyer triggers the discount, the valid values for this field are:
  5, 6, 7, 8, 9, 10, 15, 20, 25,
  30, 35, 40, 45, 50, 55, 60, 65,
  70, 75, 80, 85, 90, 95, 100, 110,
  120, 125, 150, 200, 250


For markdown promotions, the range is greater, as outlined below and detailed more precisely here: ' $ref: '#/components/schemas/Amount' amountOffOrder: description: 'Used for threshold promotions, this is the monetary amount that is discounted off an order when the promotion criteria is met. Because this field is valid only for orders, it''s not a valid combination to use with markdown promotions.

Valid values for the associated amountOffOrder.value field:
  5, 6, 7, 8, 9, 10, 15, 20, 25,
  30, 35, 40, 45, 50, 55, 60, 65,
  70, 75, 80, 85, 90, 95, 100, 110,
  120, 125, 150, 200, 250
' $ref: '#/components/schemas/Amount' percentageOffItem: type: string description: 'The percentage applied to the sales price that is discounted off the promoted item (or items) when the promotion criteria is met.

Valid integer values for percentage off:   Min: 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.

Valid integer values for ORDER_DISCOUNT promotions:   Min: 5   Max: 80

For VOLUME_DISCOUNT promotions: Must be set to 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 a CODED_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.

Required if you are creating a volume pricing promotion. format: int32 description: This complex type defines a promotion as being either a monetary amount or a percentage of a sales price that's subtracted from the price of an item or order.

Set the amount of the discount and the rules that govern when the discount triggers using the discountBenefit and discountSpecification fields.

Note: In volume pricing 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.

Valid values for the associated forEachAmount.value field:
  5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
  50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
  85, 89, 90, 95, 99, 100, 110, 120, 125,
  149, 150, 175, 199, 200, 249, 250, 299,
  300, 350, 399, 400, 450, 499, 500
' $ref: '#/components/schemas/Amount' forEachQuantity: type: integer description: The number of items that must be purchased in order to qualify for the discount.

Valid values:
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
  12, 13, 14, 15, 16, 17, 18, 19
  20, 25, 50, 75, 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.

Valid values for the associated minAmount.value field:
  5, 10, 15, 20, 25, 30, 35, 40, 45, 49,
  50, 55, 59, 60, 65, 69, 70, 75, 79, 80,
  85, 89, 90, 95, 99, 100, 110, 120,
  125, 149, 150, 175, 199, 200, 249, 250, 299,
  300, 350, 399, 400, 450, 499, 500
' $ref: '#/components/schemas/Amount' minQuantity: type: integer description: The minimum quantity of promoted items that needs to be bought in order to qualify for the promotion's discount.

Valid values:
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
  12, 13, 14, 15, 16, 17, 18, 19
  20, 25, 50, 75, 100
format: int32 numberOfDiscountedItems: type: integer description: Use this field to configure "Buy One Get One" (or BOGO) promotions.

You must couple this field with forEachQuantity and an amountOffItem or percentOffItem field to configure your BOGO promotion. This field is not valid with order-based promotions.

The value of this field represents the number of items to be discounted when other promotion criteria is met. For example, when the buyer adds the number of items identified by the forEachQuantity value to their cart, they are then eligible to receive the stated discount from an additional number of like items (the number of which is identified by this field) when they add those items to their cart. To receive the discount, the buyer must purchase the number of items indicated by forEachQuantity plus the number indicated by this field.

Valid values:
  1, 2, 3, 4, 5, 6, 7, 8, 9, 10 format: int32 description: This 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.

This specifies the maximum and minimum values to which an ad rate can be dynamically adjusted. adRateCapPercent: type: string description: The maximum value (specified as a percentage) to which the eBay suggested ad rate can be adjusted. The adjusted ad rate will never exceed this percentage. description: A type that defines the ad rate details for a Promoted Listings Standard (PLS) ad campaign. Error: type: object properties: category: type: string description: 'The category type for this error or warning. It takes an ErrorCategory object which can have one of three values:' domain: type: string description: Name of the domain containing the service or application. errorId: type: integer description: A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. format: int32 inputRefIds: type: array description: Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation. items: type: string longMessage: type: string description: An expanded version of message that should be around 100-200 characters long, but is not required to be such. message: type: string description: An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale. outputRefIds: type: array description: Identifies specific response elements associated with the error, if any. Path format is the same as 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.

The default value for this field is FIXED. If this field is omitted, the default value will be used.

Note: This field is not applicable for Cost Per Click (CPC) or Offsite Ads campaigns. For implementation help, refer to eBay API documentation biddingStrategy: type: string description: Indicates the bidding strategy for an onsite Cost Per Click (CPC) campaign that uses manual targeting.

Note: This field is not applicable for smart targeting campaigns.
Valid values are:
Default value: FIXED For implementation help, refer to eBay API documentation bidPercentage: type: string description: 'The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

The bidPercentage is a single precision value that is guided by the following rules: This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.

If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Note:This field is only relevant for campaigns that use the CPS funding model and a fixed ad rate. It is not used for campaigns that use the Cost Per Click (CPC) funding model and should not be provided when the selected adRateStrategy for the campaign is dynamic.

Note: This field has a minimum value of 2.0 and a maximum value of 100.0.' bidPreferences: type: array description: This container indicates the bidding preferences of the campaign, such as the maximum CPC amount.

Note: This container is only applicable for smart targeting campaigns.
This container is required if the user wants to create a Smart Targeting campaign. items: $ref: '#/components/schemas/BidPreference' dynamicAdRatePreferences: type: array description: A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage.

Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC This field is not applicable for Offsite Ads campaigns.
Default: 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.


Maximum: 500 parent items

Maximum SKU or custom label length: 50 characters

Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds. items: $ref: '#/components/schemas/InventoryItem' listingIds: type: array description: An array of eBay listing IDs to be added to the promotion.

Note: The request can have either inventoryItems or listingIds, but not both.


Required: All listings in a promotion must offer an electronic payment method.

Maximum: 500 parent items

Maximum SKU or custom label length: 50 characters

Required if InventoryCriterionType is set to INVENTORY_BY_VALUE, you must specify either inventoryItems or listingIds. items: type: string ruleCriteria: description: This container defines a set of inventory selection rules for a promotion.

When defining rule criteria, you must limit item exclusions to 100 IDs when you choose from live inventory.

Required if InventoryCriterionEnum is set to INVENTORY_BY_RULE or INVENTORY_ANY. $ref: '#/components/schemas/RuleCriteria' description: This type defines either the selections rules or the list of listing IDs for the 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.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify and item ID or a SKU (if the SKU is defined in the listing)

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API. description: This type defines the fields for the seller inventory reference IDs (also known as an "SKU" or "custom label"). InventoryReference: type: object properties: inventoryReferenceId: type: string description: The unique identifier of a single-item listing or a multi-variation listing.

To create an ad for a single-item listing, set the inventoryReferenceType value to INVENTORY_ITEM and specify an item ID or a SKU (if the SKU is defined in the listing).

To create an ad for a multi-variation listing, set the inventoryReferenceType value to INVENTORY_ITEM_GROUP and specify the item ID for the multi-variation listing or the inventoryitemGroupKey value as defined in the Inventory API.

Required if if you supply an inventoryReferenceType. inventoryReferenceType: type: string description: Indicates the type of item indicated by the inventoryReferenceId.

This value can be set to either INVENTORY_ITEM or INVENTORY_ITEM_GROUP.

Required if if you supply an inventoryReferenceId. For implementation help, refer to eBay API documentation description: This complex type is used to identify an item that is managed by the Inventory API. The type defines the fields contained in an inventory reference ID. ItemBasis: type: object properties: estimatedValue: type: integer description: The estimated value of the search impressions for items based on the provided dimensions.

Duration: 17 days

Total slots: 200

Channel: Dweb, Mweb, Native format: int32 metric: type: string description: The basis of the statistics. For implementation help, refer to eBay API documentation description: A container for details regarding the basis for an item. ItemMarkdownStatus: type: object properties: listingMarkdownStatus: type: string description: Indicates the state assigned to the markdown promotion using one of the status values. For implementation help, refer to eBay API documentation statusChangedDate: type: string description: Identifies the date the last time the state of the promotion changed. Both both markdown and markup events can trigger a status change. statusMessage: type: string description: An eBay-assigned text string that describes the status of the promotion. description: This type defines the status of a markdown promotion. ItemPriceMarkdown: type: object properties: applyFreeShipping: type: boolean description: If set to true, free shipping is applied to the first shipping service specified for the item. The first domestic shipping option is set to "free shipping," regardless if the shipping optionType for that service is set to FLAT_RATE, CALCULATED, or NOT_SPECIFIED (freight). This flag essentially adds free shipping as a promotional bonus.

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

Default: false blockPriceIncreaseInItemRevision: type: boolean description: If set to true, price increases (including removing the free shipping flag) are blocked and an error message is returned if a seller attempts to adjust the price of an item that's partaking in this markdown promotion. If set to false, an item is dropped from the markdown promotion if the seller adjusts the price.

Default: false description: type: string description: This field is required if you are configuring an MARKDOWN_SALE promotion.

This is the seller-defined "tag line" for the offer, such as "Save on designer shoes." A tag line appears under the "offer-type text" that is generated for the promotion. The text is displayed on the offer tile that is shown on the seller's All Offers page and on the event page for the 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".


Maximum length: 50 endDate: type: string description: The date and time the promotion ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). The value supplied for endDate must be at least 24 hours after the value supplied for the startDate of the markdown promotion.

For display purposes, convert this time into the local time of the seller.

Max value: marketplaceId: type: string description: The eBay marketplace ID of the site where the markdown promotion is hosted. Markdown promotions are supported on all eBay marketplaces. For implementation help, refer to eBay API documentation name: type: string description: The seller-defined name or 'title' of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows.

Maximum length: 90 priority: type: string description: This field is ignored in markdown promotions. For implementation help, refer to eBay API documentation promotionImageUrl: type: string description: Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, populate this field with a URL that points to an image to be used with the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size. promotionStatus: type: string description: The current status of the promotion. When creating a new promotion, you must set this value to either DRAFT or SCHEDULED.

Note that you must set this value to 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.

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: 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 on the offer tile that's shown on the seller's All Offers page, and on the event page for the 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. The offer-type text is not editable by the seller—it's derived from the settings in the discountRules and discountSpecification fields—and can be, for example, "Extra 20% off when you buy 3+".


Maximum length: 50

Required if you are configuring CODED_COUPON, ORDER_DISCOUNT, or MARKDOWN_SALE promotions (and not valid for VOLUME_DISCOUNT promotions). discountRules: type: array description: 'This container defines a promotion using the following two required fields:

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:

For implementation help, refer to eBay API documentation name: type: string description: The seller-defined name or "title" of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows.

Maximum length: 90 priority: type: string description: Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which is used to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation promotionImageUrl: type: string description: Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not valid for VOLUME_DISCOUNT promotions.

Populate this field with a URL that points to an image to be used with the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size. promotionStatus: type: string description: The current status of the promotion. When creating a new promotion, this value must be set to either DRAFT or SCHEDULED.

Note that you must set this value to 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:

See the Promotions Manager documentation for details.

Required if you are creating a volume pricing promotion (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 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+".


Maximum length: 50 discountRules: type: array description: A list containing the promotion benefits (discountRule) and the rules that define when the benefit is applied (discountSpecification). items: $ref: '#/components/schemas/DiscountRule' endDate: type: string description: The date and time the 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: 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:

For implementation help, refer to eBay API documentation name: type: string description: The seller-defined name or "title" of the promotion that the seller can use to identify a promotion. This label is not displayed in end-user flows.

Maximum length: 90 priority: type: string description: Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which eBay uses to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation promotionId: type: string description: A unique eBay-assigned ID for the promotion that's generated when the promotion is created. promotionImageUrl: type: string description: Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not applicable for VOLUME_DISCOUNT promotions, this field is a URL that points to an image for the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size. promotionStatus: type: string description: The current status of the promotion. When creating a new promotion, this value must be set to either DRAFT 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.

Max length: 2048' offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

' format: int32 prev: type: string description: 'The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048' total: type: integer description: The total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 0. format: int32 warnings: type: array description: A list of warnings that were generated by the request. Warning do not stop processing, but should be checked to ensure that the response contains the correct information. items: $ref: '#/components/schemas/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.

Valid Values: For implementation help, refer to eBay API documentation keywordText: type: string description: The text of the keyword. matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation description: A type that contains the details for keywords that are associated with an ad group.

Note: This type only applies to the Cost Per Click (CPC) funding model; it does not apply to the Cost Per Sale (CPS) funding model. KeywordPagedCollectionResponse: type: object properties: href: type: string description: The URI of the current page of results from the result set. keywords: type: array description: This array contains all of the keywords that match the request criteria. Keywords will be sorted by adGroupId, regardless of whether you searched for keywords across the entire campaign, or if you searched for keywords within one or specific ad groups. items: $ref: '#/components/schemas/Keyword' limit: type: integer description: The number of keywords returned on a single page from the result set. This value can be set in the request with the limit query parameter. format: int32 next: type: string description: 'The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set.

Max length: 2048' offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

' format: int32 prev: type: string description: 'The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results.

Max length: 2048' total: type: integer description: The total number of keywords retrieved in the result set.

If no keywords are found, this field is returned with a value of 0. format: int32 description: A type that defines the keywords of the paged collection. KeywordRequest: type: object properties: keywordText: type: string description: 'The text of the keyword. Keywords are not case sensitive and compound words can be used without additional encoding (for example, tennis ball).

You can use the getKeywords method to retrieve keyword values currently associated with the specified ad group.

Maximum number of characters: 100

Maximum number of words: 10 ' matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation description: A type that defines the fields used by the Keyword method. KeywordResponse: type: object properties: adGroupId: type: string description: The identifier of the ad group that the keyword was added to. errors: type: array description: This container will be returned if there is an issue creating the corresponding keyword and/or adding that keyword to the corresponding ad group. items: $ref: '#/components/schemas/Error' href: type: string description: The getKeyword URI for the keyword, which is used to retrieve the keyword. This URI will be returned for each successfully created keyword. keywordId: type: string description: A unique eBay-assigned ID for a keyword that is generated for an ad group. This keyword ID will be generated for each successfully created keyword. keywordText: type: string description: The text of the keyword. matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation statusCode: type: integer description: An HTTP status code is returned for each keyword to indicate the success or failure of adding that keyword to the ad group. format: int32 warnings: type: array description: List of warnings associated with this operation items: $ref: '#/components/schemas/Error' description: A type that defines the response fields used by the Keyword method. ListingDetail: type: object properties: currentPrice: description: The container that returns the current price of the listing. $ref: '#/components/schemas/Amount' freeShipping: type: boolean description: If set to true, the seller pays for the shipping (or that the item is marked for local pickup only) In this case, the listing does not have an associated shipping cost for the first listed domestic-shipping option (even if the first domestic-shipping option specifies a flat-rate or calculated shipping option). If false, the buyer is required to pay for a flat-rate or calculated cost shipping service. inventoryReferenceId: type: string description: The seller's inventory reference ID for a listing. Also known as the "SKU" or "custom label," an inventory reference ID is either the ID of the listing or, if the listing has variations (such as a shirt that's available in multiple sizes and colors), the ID of the parent listing. inventoryReferenceType: type: string description: Indicates the type of the inventoryReferenceId, which can be either a single-SKU or a multi-SKU listing (INVENTORY_ITEM and INVENTORY_ITEM_GROUP, respectively).

Note: This value is not currently returned in the response. listingCategoryId: type: string description: The ID of the category that listing belongs to. The ID is a numeric and unique identifier for the category that is assigned by eBay. listingCondition: type: string description: An eBay-assigned value that indicates condition of the associated item. For more information, see Item condition ID and name values. listingConditionId: type: string description: 'The ID of the condition associated with the item. For more information, see Item condition ID and name values.

Note: This value is not currently returned in the response.' listingId: type: string description: A unique eBay-assigned ID that is generated when the item is listed. listingPromotionStatuses: type: array description: A list of the status values assigned to the item and the date that each new status was assigned. items: $ref: '#/components/schemas/ItemMarkdownStatus' quantity: type: integer description: The number of items being sold in the listing. format: int32 storeCategoryId: type: string description: Store CategoryId (if any) that to which the listing belongs. This field is blank if there is no seller Store category ID. title: type: string description: The seller-defined title of the listing that a seller can use to identify the item. This label is not displayed in end-user flows. description: This type defines the fields that describe a listing that is in a promotion. MaxCpc: type: object properties: amount: description: The allocated maximum CPC amount for a smart targeting campaign.

Both the currency and amount must be specified when allocating the Max CPC. $ref: '#/components/schemas/Amount' MetricMetadata: type: object properties: dataType: type: string description: The data type of the returned metric value. For implementation help, refer to eBay API documentation metricKey: type: string description: The name of the metric. description: This type defines the name and data type of a metric. NegativeKeyword: type: object properties: adGroupId: type: string description: An ad group ID that is generated when an ad group is first created and associated with a campaign.

Note: You can call the getAdGroups method to retrieve the ad group IDs for a seller. campaignId: type: string description: A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created. negativeKeywordId: type: string description: A unique eBay-assigned ID for a negative keyword. This keyword ID will be generated for each successfully created negative keyword. negativeKeywordMatchType: type: string description: A field that defines the match type for the negative keyword.

Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation negativeKeywordStatus: type: string description: A field that defines the status of the negative keyword. For implementation help, refer to eBay API documentation negativeKeywordText: type: string description: The text for the negative keyword. description: A type that defines the fields for a negative keyword. NegativeKeywordPagedCollectionResponse: type: object properties: href: type: string description: The URI of the current page of results from the result set. limit: type: integer description: The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter. format: int32 negativeKeywords: type: array description: A list of negative keywords returned in the paginated collection. items: $ref: '#/components/schemas/NegativeKeyword' next: type: string description: The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set. offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Default: 0

Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.' format: int32 prev: type: string description: The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results. total: type: integer description: The total number of result sets in the paginated collection. format: int32 description: A type that defines the negative keywords, returned in a paged collection. NegativeKeywordResponse: type: object properties: adGroupId: type: string description: A unique identifier for an ad group that is generated when an ad group is first created and associated with a campaign. campaignId: type: string description: A unique eBay-assigned ID for a campaign. This ID is generated when a campaign is created. errors: type: array description: This container will be returned if there is an issue creating the corresponding negative keyword. items: $ref: '#/components/schemas/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.

Note: Broad matching of negative keywords is not currently supported.
Valid Values: For implementation help, refer to eBay API documentation negativeKeywordText: type: string description: The text for the negative keyword. statusCode: type: integer description: The status of the request to create a negative keyword. This field indicates whether the process was successful or not. format: int32 description: A type that defines the negative keyword response. PriceRange: type: object properties: currency: type: string description: Specifies the currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type. gte: type: number description: The listings selected will be greater than or equal to this value. The value entered must be given in number format, such as 20.00.

Either gte, lte, or both must contain a value if the seller wishes to use a price range. lte: type: number description: The listings selected will be less than or equal to this value. The value entered must be given in number format, such as 100.00.

Either gte, lte, or both must contain a value if the seller wishes to use a price range. description: 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+".


Maximum length: 50

Required if you are configuring ORDER_DISCOUNT or MARKDOWN_SALE promotions (and not valid for VOLUME_DISCOUNT promotions). 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. 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:

For implementation help, refer to eBay API documentation name: type: string description: The seller-defined name or "title" of the promotion, such as "Buy 1 Get 1", that the seller can use to identify a promotion. This label is not displayed in end-user flows.

Maximum length: 90 priority: type: string description: Applicable for only ORDER_DISCOUNT promotions, this field indicates the precedence of the promotion, which is used to determine the position of a promotion on the seller's All Offers page. If an item is associated with multiple promotions, the promotion with the higher priority takes precedence. For implementation help, refer to eBay API documentation promotionHref: type: string description: The URI of the promotion details. promotionId: type: string description: A unique eBay-assigned ID for the promotion that's generated when the promotion is created. promotionImageUrl: type: string description: Required for CODED_COUPON, MARKDOWN_SALE, and ORDER_DISCOUNT promotions, and not applicable for VOLUME_DISCOUNT promotions, this field is a URL that points to an image for the promotion. This image is displayed on the seller's All Offers page. The URL must point to either JPEG or PNG image and it must be a minimum of 500x500 pixels in dimension and cannot exceed 12Mb in size. promotionStatus: type: string description: The current status of the promotion. When creating a new promotion, you must set this value to either DRAFT 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:

totalDiscount / itemsSoldQuantity = averageItemDiscount' $ref: '#/components/schemas/Amount' averageItemRevenue: description: 'The average item revenue is the average revenue that has been received for each item in a promotion. This value is calculated as follows:

totalSales / itemsSoldQuantity = averageItemRevenue' $ref: '#/components/schemas/Amount' averageOrderDiscount: description: 'The average order discount is the average discount that has been applied to each order in a promotion. This value is calculated as follows:

totalDiscount / numberOfOrdersSold = averageOrderDiscount' $ref: '#/components/schemas/Amount' averageOrderRevenue: description: 'The average order revenue is the average revenue that has been received for each order in a promotion. This value is calculated as follows:

totalSales / numberOfOrdersSold = averageOrderRevenue' $ref: '#/components/schemas/Amount' averageOrderSize: type: string description: 'The average order size is the average number of items that each order contained in a promotion. This value is calculated as follows:

itemsSoldQuantity / numberOfOrdersSold = averageOrderSize ' baseSale: description: This is the monetary amount of items purchased in a promotion where the threshold wasn't met, so the discount was not applied.

For example, suppose you're running a "Buy 1, get 1 at 50%" promotion on $5 socks. One buyer purchased only one pair of socks, so they pay the full price of $5. Here, your baseSale amount would be $5. $ref: '#/components/schemas/Amount' itemsSoldQuantity: type: integer description: This is the quantity of items purchased in a threshold promotion where the threshold has been met and the discount was applied.

For example, suppose you're running a "Buy 1, get 1 at 50%" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your number of items sold (itemsSoldQuantity) would be 2 and you number of orders sold (numberOfOrdersSold) would be 1. format: int32 numberOfOrdersSold: type: integer description: This is the number of orders sold in a threshold promotion where the threshold has been met and the discount was applied.

For example, suppose you're running a "Buy 1, get 1 at 50%" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your numberOfOrdersSold would be 1 and your itemsSoldQuantity would be 2. format: int32 percentageSalesLift: type: string description: 'The percentage sales lift is the total dollar amount gained due to promotions. This value is calculated as follows:

promotionSale / totalSale = percentageSalesLift ' promotionHref: type: string description: The URI of the promotion report. promotionId: type: string description: A unique eBay-assigned ID for the promotion that's generated when the promotion is created. promotionReportId: type: string description: The unique eBay-assigned ID of the promotion report that is generated when the report is created. promotionSale: description: This is the monetary amount of the items sold in a threshold promotion where the threshold has been met and the discount was applied.

For example, suppose you're running a "Buy 1, get 1 at 50%" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your promotionSale amount would be $7.50. $ref: '#/components/schemas/Amount' promotionType: 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 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.

For example, suppose you're running a "Buy 1, get 1 at 50%" promotion on $5 socks. One buyer purchases two pairs of socks, so they pay $7.50 for both pairs (rather than the full price of $10). Your totalDiscount amount would be $2.50. $ref: '#/components/schemas/Amount' totalSale: description: 'This is the total monetary sales amount of all items sold in a promotion.

For example, suppose you''re running a "Buy 1, get 1 at 50%" promotion on $5 socks. You make one sale where the buyer purchases only one pair of socks and they pay the full price of $5 (baseSale). You make a second sale where the buyer purchases two pairs of socks and they pay $7.50, for both pairs (promotionSale). Your totalSale would be $12.50. This value is calculated as follows:

baseSale + promotionSale = totalSale' $ref: '#/components/schemas/Amount' description: This type defines the fields in a promotion-level report. PromotionsPagedCollection: 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.

Max length: 2048' offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

' format: int32 prev: type: string description: 'The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048' promotions: type: array description: A list containing the details of each returned promotion. This includes all the information about the promotions except for the listings that are part of the promotions. items: $ref: '#/components/schemas/PromotionDetail' total: type: integer description: The total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 0. format: int32 description: 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.

Max length: 2048' offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

' format: int32 prev: type: string description: 'The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048' promotionReports: type: array description: A list of promotionReports contained in the paginated result set. items: $ref: '#/components/schemas/PromotionReportDetail' total: type: integer description: The total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 0. format: int32 description: 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.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to eBay API documentation rangeEnd: type: string description: The end of the range specified for the bid. rangeStart: type: string description: The start of the range specified for the bid. value: type: string description: The value of the proposed bid. description: A type that defines the data for a payment amount, such as the sale price. QuickSetupRequest: type: object properties: budget: description: The allocated daily budget for a Promoted Listings campaign that uses the Cost Per Click (CPC) funding model. $ref: '#/components/schemas/CampaignBudgetRequest' campaignName: type: string description: 'The seller-defined name for the campaign. This value must be unique for the seller.

You can use any alphanumeric characters in the name, except for the less than (<) and greater than (>) characters.

Max Length: 80 characters' endDate: type: string description: 'The date and time the campaign is scheduled to end, in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).

If this field is omitted, the campaign will have no defined end date, and will not end until the seller ends the campaign using the endCampaign method, or if they update the campaign to include an end date using the updateCampaignIdentification method. This date must be further in the future than the startDate. ' listingIds: type: array description: 'This array includes the listing Ids of the items that are to be associated with the PLA campaign. eBay will create ad groups and keywords for these listings and add them to the campaign.

Each value must be delimited by a comma. A maximum of 1000 listing Ids can be added to a campaign created using the setupQuickCampaign method. ' items: type: string marketplaceId: type: string description: The Id of the marketplace where the campaign is hosted. See the MarkeplaceIdEnum type for more details. For implementation help, refer to eBay API documentation startDate: type: string description: The date and time the campaign is scheduled to start, in UTC format (yyyy-MM-ddThh:mm:ss.sssZ).

On the specified date, 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 once 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.

Note: If the startDate has passed by the time the seller launches a campaign, the campaign will be updated to 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.

Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. For implementation help, refer to eBay API documentation description: This type defines the fields included in the report. ReportMetadatas: type: object properties: reportMetadata: type: array description: A list of the metadata for the associated report type. items: $ref: '#/components/schemas/ReportMetadata' description: This type defines the metadata used by the all report types. ReportTask: type: object properties: campaignIds: type: array description: A list of IDs for the campaigns that are included in the report. A campaign ID is a unique eBay-assigned identifier of the campaign that's generated when the campaign is created.

Call getCampaigns to return the current campaign IDs for a seller. items: type: string channels: type: array description: The channel for the advertising campaign that will be included in the report task. This value indicates whether the data included in the report task is for an Onsite or Offsite advertising campaign. items: 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, formatted as an ISO 8601 timestamp. dateTo: type: string description: The date defining the end of the timespan covered by the report, formatted as an ISO 8601 timestamp. dimensions: type: array description: A list containing the dimension in the report. items: $ref: '#/components/schemas/Dimension' fundingModels: type: array description: The funding model for the campaign that shall be included in the report.

Note: The default funding model for Promoted Listings reports is COST_PER_SALE.

Valid Values: items: type: string description: ' For implementation help, refer to eBay API documentation' inventoryReferences: type: array description: If supplied in the request, this field returns a list of the seller's inventory reference IDs included in the report.

Each item is referenced by a pair of inventoryRefernceID and inventoryReferenceType values, where an inventory reference ID can be either a seller-defined SKU value or an inventoryItemGroupKey. An inventoryItemGroupKey is seller-defined ID for an inventory item group (a multiple-variation listing), and is created and used by the Inventory API.

items: $ref: '#/components/schemas/InventoryReference' listingIds: type: array description: If supplied in the request, this field returns a list of the listing IDs included in the report. A listing ID is an eBay-assigned ID that's generated when a listing is created. items: type: string marketplaceId: 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.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ' reportFormat: type: string description: Indicates the format of the report. Currently, only 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.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ' reportTaskCreationDate: type: string description: 'The date the report task was created.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ' reportTaskExpectedCompletionDate: type: string description: 'The date the report task is expected to complete the report generation.

Format (UTC): yyyy-MM-ddThh:mm:ss.sssZ' reportTaskId: type: string description: The unique eBay-assigned ID of the report task. This value is generated when the report task is created with a call to createReportTask. reportTaskStatus: type: string description: Indicates the current state of the report task. For implementation help, refer to eBay API documentation reportTaskStatusMessage: type: string description: A status message with additional information about the report task. reportType: type: string description: Indicates type of report associated with the report task.

Note: INVENTORY_PERFORMANCE_REPORT is not currently available; availability date is pending. For implementation help, refer to eBay API documentation description: This type defines the fields in a report task. ReportTaskPagedCollection: 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.

Max length: 2048' offset: type: integer description: The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0. format: int32 prev: type: string description: 'The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048' total: type: integer description: The total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 0. format: int32 reportTasks: type: array description: A list of report tasks contained on this page from the paginated response. items: $ref: '#/components/schemas/ReportTask' description: This type defines the fields that paginate the reports tasks returned by the request. The entire result set consists of 0 or more sequenced response pages, where each page consists of 0 or more items from the complete result set. 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 items

Maximum SKU or custom label length: 50 characters items: $ref: '#/components/schemas/InventoryItem' excludeListingIds: type: array description: A list of eBay listing IDs to exclude from the promotion.

Note: The request can have either excludeInventoryItems or excludeListingIds but not both.

Maximum: 100 parent items
Maximum SKU or custom label length: 50 characters items: type: string markupInventoryItems: type: array description: A list of SKUs to remove from a markdown promotion. The listed SKUs are 'marked up' to their standard price after being part of the markdown promotion. items: $ref: '#/components/schemas/InventoryItem' markupListingIds: type: array description: A list of listing IDs to remove from a markdown promotion. The listed items are 'marked up' to their standard price after being part of the markdown promotion. items: type: string selectionRules: type: array description: The container for the rules that select the items to include in a promotion.

Required if inventoryCriterionType is set to INVENTORY_BY_RULE.

For information on using the contained fields, see Item promotions. items: $ref: '#/components/schemas/SelectionRule' description: This type defines the fields for a set of inventory selection rules.

Required: When inventoryCriterionType is set to INVENTORY_BY_RULE or INVENTORY_ANY. 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).

For Item promotions, a single-item array containing the category ID associated with the promotion. Required when used in an Item promotion and either specifying a selectionRules container or when inventoryCriterionType is set to INVENTORY_BY_RULE.

For Promoted Listing campaigns, an array of category ID(s) associated with the campaign.

For information on how to get category IDs, see eBay Marketplace category IDs and Seller store category IDs items: type: string categoryScope: type: string description: This enumerated value indicates if the category ID for the item is an identifier for eBay categories or for a seller's eBay store categories.

For Promoted Listing campaigns, this field includes the type of the category ID for the item(s) to be included in the campaign.

For Item promotions, this field identifies the scope for the corresponding array as eBay categories or for a seller's eBay store categories. Required when used in an Item promotion and inventoryCriterionType is set to 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 included

For Promoted Listing campaigns, refer to Add items to the PLS campaign. Up to four IDs can be specified.

For Item promotions, refer to Item condition ID and name values. items: type: string maxPrice: description: This container sets the maximum price threshold. For more details, see Using the selectionRules container. $ref: '#/components/schemas/Amount' minPrice: description: This container sets the minimum price threshold. For more details, see Using the selectionRules container. $ref: '#/components/schemas/Amount' description: This type defines all rules/inclusion filters used to add listings to campaigns or promotions. Use of the specific fields is different for campaigns or promotions. See Using the selectionRules container. SuggestBudgetResponse: type: object properties: suggestedBudget: type: array description: The suggested allocated daily budget for an Offsite Ads campaign. items: $ref: '#/components/schemas/BudgetRecommendationResponse' description: This type defines the fields used in the suggestBudget response. SuggestedBids: type: object properties: keywordText: type: string description: The text for the keyword. matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation proposedBid: description: 'The suggested bid associated with the keyword. ' $ref: '#/components/schemas/ProposedBid' description: The suggested bid rate for the item. SuggestedKeywords: type: object properties: additionalInfo: type: array description: 'A container for the additional information and compiled insight data for suggested keywords. ' items: $ref: '#/components/schemas/AdditionalInfo' keywordText: type: string description: The text for the keyword. matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation description: The suggested keywords for the item. SummaryReportResponse: type: object properties: baseSale: description: The total revenue from all the purchased items that were part of a promotion but did not trigger a discount during the promotion period. $ref: '#/components/schemas/Amount' lastUpdated: type: string description: The date the report was generated. percentageSalesLift: type: string description: 'The percentage of the total dollar amount gained due to promotions. This value is calculated as follows:

precentageSalesLift = promotionSale / (baseSale + promotionSale)' promotionSale: description: The total revenue from all the purchased items that were part of a promotion and their purchase did trigger a discount during the promotion period. $ref: '#/components/schemas/Amount' totalSale: description: Total dollar sales amount of all the seller's listings, current to the date the report was generated. $ref: '#/components/schemas/Amount' description: This type defines the fields in an Promotions Manager Summary report. Reports are formatted in JSON. For more details, see Reading item promotion Summary reports. TargetedAdsPagedCollection: type: object properties: href: type: string description: The URI of the current page of results from the result set. limit: type: integer description: The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter. format: int32 next: type: string description: The call URI that can be used to retrieve the next page in the result set. This value is returned only if there is an additional page of results to display from the result set. offset: type: integer description: 'The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Default: 0


Note: The items in a paginated result set use a zero-based list, where the first item in the list has an offset of 0.' format: int32 prev: type: string description: The call URI that can be used to retrieve the previous page in the result set. Basically, all of the request parameters will remain the same except the offset value, which will be decreased to retrieve the previous page of results. suggestedItems: type: array description: A list of suggested items in the paginated collection. items: $ref: '#/components/schemas/TargetingItems' total: type: integer description: 'The total number of items retrieved in the result set.

Note: If no items are found, this field is returned with a value of 0.' format: int32 description: A type that defines the keywords of the paged collection. TargetedBidRequest: type: object properties: keywords: type: array description: 'An array of keywords for which bids will be required.

Maximum number of keywords: 500' items: $ref: '#/components/schemas/KeywordRequest' description: A type that defines the targeted bid. TargetedBidsPagedCollection: type: object properties: suggestedBids: type: array description: A list of bids in the paginated collection. items: $ref: '#/components/schemas/SuggestedBids' description: A type that defines the keywords of the paged collection. TargetedKeywordRequest: type: object properties: additionalInfo: type: array description: A field used to indicate whether additional information and insight data shall be provided for suggested keywords.

Use this array to retrieve keyword insights, including active seller count and search volume.

Valid Value: KEYWORD_INSIGHTS items: 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.

Valid Value: 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.

Maximum number of listings requested: 300' items: type: string matchType: type: string description: A field that defines the match type for the keyword.

Valid Values: For implementation help, refer to eBay API documentation description: A type that provides details for the targeted keywords. TargetedKeywordsPagedCollection: type: object properties: suggestedKeywords: type: array description: 'A list of suggested keywords in the paged collection.

Note: A relevancy check with items already present in the ad-group is performed even if item IDs associated with the ad-group are not explicitly passed in the request.

' items: $ref: '#/components/schemas/SuggestedKeywords' description: A type that defines the keywords of the paged collection. TargetingItems: type: object 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:

For implementation help, refer to eBay API documentation defaultBid: description: A bid amount that applies to all of the keywords in an ad group that do not have individual bids. $ref: '#/components/schemas/Amount' name: type: string description: The updated name for the specified ad group. description: A type that contains the fields used by the UpdateAdGroup request. UpdateAdStatusByListingIdRequest: type: object properties: adGroupId: type: string description: A unique eBay-assigned ID for an ad group in a campaign that uses the Cost Per Click (CPC) funding model.

Use the getAdGroups method to retrieve the ad group IDs for a seller. adStatus: type: string description: An enumeration value representing the current status of the ad.

Valid Values: For implementation help, refer to eBay API documentation listingId: type: string description: A unique eBay-assigned identifier for a listing that is generated when the listing is created.

Note: This field accepts both listing IDs (as generated by the Inventory API), and item IDs (as used in the eBay Traditional API set, such as the Trading and Finding APIs). description: A type that contains the fields for the UpdateAdStatusByListingId request. UpdateAdStatusRequest: type: object properties: adId: type: string description: A unique eBay-assigned identifier for an ad that belongs to the specified campaign.

Use the getAds method to retrieve ad IDs. adStatus: type: string description: An enumeration value representing the status you wish to update the specified ad to.

Valid Values: For implementation help, refer to eBay API documentation description: A type that contains the fields for the UpdateAdStatus request. UpdateAdrateStrategyRequest: type: object properties: adRateStrategy: type: string description: This field is used to change the current ad rate strategy for a Cost Per Sale (CPS) campaign. It is not needed if the ad rate strategy is not being changed for the campaign.

Note: This field is not applicable for Offsite Ads campaigns. For implementation help, refer to eBay API documentation bidPercentage: type: string description: 'The user-defined bid percentage (also known as the ad rate) sets the level that eBay increases the visibility in search results for the associated listing. The higher the bidPercentage value, the more eBay promotes the listing.

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

The bidPercentage is a single precision value that is guided by the following rules: This is the default bid percentage for the campaigns using the Cost Per Sale (CPS) funding model, and this value will be overridden by any ads in the campaign that have their own set bid percentages.

If a bid percentage is not provided for an ad, eBay uses the default bid percentage of the associated campaign.

Note: This field has a minimum value of 2.0 and a maximum value of 100.0.' dynamicAdRatePreferences: type: array description: A field that indicates whether a single, user-defined bid percentage (also known as the ad rate) should be used, or whether eBay should automatically adjust listings to maintain the daily suggested bid percentage.

Note: Dynamic adjustment is only applicable when the adRateStrategy is set to DYNAMIC.
Default: FIXED items: $ref: '#/components/schemas/DynamicAdRatePreference' description: A type that defines the request fields used to update the ad rate strategy for a Promoted Listings ad campaign. UpdateAdsByInventoryReferenceResponse: type: object 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.

The value specified here is also used to calculate the Promoted Listings fee. This percentage value is multiplied by the final sales price to determine the fee.

The Promoted Listings fee is determined at the time the transaction completes and the seller is assessed the fee only when an item sells through a Promoted Listings ad campaign.

The bidPercentage is a single precision value that is guided by the following rules:
Note: This field has a minimum value of 2.0 and a maximum value of 100.0.' description: This type specifies the bid percentage for an ad campaign. UpdateBiddingStrategyRequest: type: object 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 bidPreferences: type: array description: This container indicates the bidding preferences of the campaign, such as the maximum CPC amount.

Note: This container is only applicable for smart targeting campaigns.
This container is required if the user wants to create a Smart Targeting campaign. items: $ref: '#/components/schemas/BidPreference' description: This type defines the fields used in the updatedBiddingStrategy request. UpdateCampaignBudgetRequest: type: object properties: daily: description: The daily budget limit for the Cost Per Click (CPC) Promoted Listings campaign. This will be a dollar value. All clicks using the keywords defined for the campaign will go towards expending the daily budget. Once the daily budget is exceeded for the campaign, all Promoted Listings under the campaign will be turned off until the next day.

Valid Values: $ref: '#/components/schemas/BudgetRequest' description: A type that contains the fields for the UpdateCampaignBudget request. UpdateCampaignIdentificationRequest: type: object properties: campaignName: type: string description: 'The new seller-defined name for the campaign. This value must be unique for the seller.

If you don''t want to change the name of the campaign, specify the current campaign name in this field.

You can use any alphanumeric characters in the name, except the less than (<) or greater than (>) characters.

Max length: 80 characters.' endDate: type: string description: The date and time the campaign ends, in UTC format (yyyy-MM-ddThh:mm:ssZ). If this field is omitted, the campaign will have no defined end date, and will not end until the seller makes a decision to end the campaign with an endCampaign call, or if they update the campaign at a later time with an end date.

If you want to change only the end date of the campaign, you must specify the current campaign name, set the endDate as desired, and set the startDate to the actual start date of the campaign. This applies if the campaign status is RUNNING or PAUSED. You can retrieve the startDate using the getCampaign method.

Note that if you do not set a new end date in this call, any current endDate value will be set to null. To preserve the currently-set end date, you must specify the value again in your request.

startDate: type: string description: The new start date for the campaign, in UTC format (yyyy-MM-ddThh:mm:ssZ).

If the campaign status is RUNNING or PAUSED, the startDate must be specified and must be the actual start date of the campaign, even if you are only changing the endDate. You can retrieve the campaign's startDate using the getCampaign method.

On the date specified, the service derives the keywords for each listing in the campaign, creates an ad for each listing, and associates each new ad with the campaign. The campaign starts after this process is completed. The amount of time it takes the service to start the campaign depends on the number of listings in the campaign.

Call getCampaigns to retrieve the campaign_id and the campaign status (RUNNING, PAUSED, ENDED, and so on) for all the seller's campaigns.

description: This type specifies the updated name, and start and end dates for an update-campaign request. UpdateCampaignRequest: type: object properties: audienceCodes: type: array description: 'An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no limit to the number of audience codes that may be entered.

Example: if the current email campaign contains "audienceCodes": "code1", "code2" and the user wishes to add an audience code code3, set the audienceCodes value to "audienceCodes": "code1", "code2", "code3".

To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes.' items: type: string categoryId: type: string description: The unique identifier of either an eBay category or a store category.

This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category.

To retrieve eBay categories, use the getCategories or Taxonomy API. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request.

itemSelectMode must be set to AUTO in order to use a category ID. categoryType: 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.

Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing.

The maximum number of itemIds for the COUPON campaign type is 4, and for every other campaign type is 10.

itemSelectMode must be set to MANUAL in order to use this field. items: type: string itemSelectMode: type: string description: 'Determines whether listings featured in an email campaign are selected by the seller or by eBay.

If itemSelectMode is set to AUTO, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange.

If itemSelectMode is set to MANUAL, listings are set by the seller by populating the itemIds array.

Note: itemSelectMode is always set to AUTO for WELCOME email campaigns. 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.

The priceRange container consists of the currency, gte, and lte fields.

"gte" stands for "greater than or equal to" and "lte" stands for "less than or equal to". Either gte, lte, or both must be used if the seller wishes to include a price range.

Note: Use this object when the itemSelectMode is set to AUTO.' $ref: '#/components/schemas/PriceRange' promotionId: type: string description: The ID of the promotion used for an email campaign if the emailCampaignType is set to COUPON, SALE_EVENT, or ORDER_DISCOUNT, and promotionSelectModeEnum is set to MANUAL.

To find a promotion, call getPromotions to retrieve a list of the seller's promotions. Use the promotionId from an individual PromotionDetail result for the request. promotionSelectModeEnum: type: string description: The selection mode for the promotion used. If set to 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.

This field is required if the emailCampaignType is set to 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:35Z

This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated.' sort: type: string description: The sort rule is used to display the listings featured in the email campaign.

Sort rules are only used if itemSelectMode is set to AUTO. If itemSelectMode is MANUAL, listings are displayed in the order in which they are listed in the itemIds array.

The following sort rules are available:

The default sort rule is 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