Lap-Platform Marketing API
API version: v1.22.2
Auth
OAuth2
Base URL
https://api.ebay.com/sell/marketing/v1
Setup
- Configure auth: OAuth2
- GET /ad_campaign -- verify access
- POST /ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference -- create first bulk_create_ads_by_inventory_reference
Endpoints
82 endpoints across 13 groups. See references/api-spec.lap for full details.
ad_campaign
| Method | Path | Description |
|---|---|---|
| POST | /ad_campaign/{campaign_id}/bulk_create_ads_by_inventory_reference | This method adds multiple listings that are managed with the Inventory API to an existing Promoted Listings campaign.For general strategy campaigns using the Cost Per Sale (CPS) model, bulk ads may be directly created for the listing.For each listing specified in the request, this method:Creates an ad for the listing. Sets the bid percentage (also known as the ad rate) for the ads created. Associates the ads created with the specified campaign.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. |
| POST | /ad_campaign/{campaign_id}/bulk_create_ads_by_listing_id | 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 general strategy campaigns using the Cost Per Sale (CPS) funding model, bulk ads may be directly created for the listing.For each listing ID specified in the request, this method: Creates an ad for the listing. Sets the bid percentage (also known as the ad rate) for the ad. Associates the ad with the specified campaign.To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.You can specify a maximum of 500 listings per call and each campaign can have ads for a maximum of 50,000 items. Be aware when using this call that each variation in a multiple-variation listing creates an individual ad.For manual targeting priority strategy campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, ads cannot be created.Note: Ad groups are not required when adding listings to a smart targeting campaign.For the ad group specified in the request, this method associates the ad with the specified ad group.To create an ad for an ad group, specify the name of the ad group plus the defaultBid for the ad in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method. You can specify one or more ad groups per campaign.Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns. |
| POST | /ad_campaign/{campaign_id}/bulk_delete_ads_by_inventory_reference | 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. |
| POST | /ad_campaign/{campaign_id}/bulk_delete_ads_by_listing_id | 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. |
| POST | /ad_campaign/{campaign_id}/bulk_update_ads_bid_by_inventory_reference | 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. |
| POST | /ad_campaign/{campaign_id}/bulk_update_ads_bid_by_listing_id | 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. |
| POST | /ad_campaign/{campaign_id}/bulk_update_ads_status | Note: This method is only available for select partners who have been approved for the priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, 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. |
| POST | /ad_campaign/{campaign_id}/bulk_update_ads_status_by_listing_id | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, 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. |
| GET | /ad_campaign/{campaign_id}/ad | 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. |
| POST | /ad_campaign/{campaign_id}/ad | 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 general strategy campaigns using the Cost Per Sale (CPS) funding model, an ad may be directly created for the listing.For the listing ID specified in the request, this method: Creates an ad for the listing. Sets the bid percentage (also known as the ad rate) for the ad. Associates the ad with the specified campaign. To create an ad for a listing, specify its listingId, plus the bidPercentage for the ad in the payload of the request. Specify the campaign to associate the ad with using the campaign_id path parameter. Listing IDs are generated by eBay when a seller creates listings with the Trading API.For manual targeting priority strategy campaigns using the Cost Per Click (CPC) funding model, an ad group must be created first. If no ad group has been created for the campaign, ads cannot be created.Note: Ad groups are not required when adding listings to a smart targeting campaign.For the ad group specified in the request, this method associates the ad with the specified ad group.To create an ad for an ad group, specify the name of the ad group in the payload of the request. Specify the campaign to associate the ads with using the campaign_id path parameter. Ad groups are generated using the createAdGroup method. You can specify one or more ad groups per campaign.Use createCampaign to create a new campaign and use getCampaigns to get a list of existing campaigns.This call has no response payload. If the ad is successfully created, a 201 Created HTTP status code and the getAd URI of the ad are returned in the location header. |
| POST | /ad_campaign/{campaign_id}/create_ads_by_inventory_reference | This method adds a listing that is managed with the Inventory API to an existing Promoted Listings campaign.For general strategy 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:Creates an ad for the listing. Sets the bid percentage (also known as the ad rate) for the ads created. Associates the created ad with the specified campaign.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. |
| GET | /ad_campaign/{campaign_id}/ad/{ad_id} | 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. |
| DELETE | /ad_campaign/{campaign_id}/ad/{ad_id} | 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. |
| POST | /ad_campaign/{campaign_id}/delete_ads_by_inventory_reference | 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. |
| GET | /ad_campaign/{campaign_id}/get_ads_by_inventory_reference | 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. |
| POST | /ad_campaign/{campaign_id}/ad/{ad_id}/update_bid | 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. |
| GET | /ad_campaign/{campaign_id}/ad_group | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, 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. |
| POST | /ad_campaign/{campaign_id}/ad_group | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, use the getAdvertisingEligibility method in Account API.This method adds an ad group to an existing priority strategy 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. |
| GET | /ad_campaign/{campaign_id}/ad_group/{ad_group_id} | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, 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. |
| PUT | /ad_campaign/{campaign_id}/ad_group/{ad_group_id} | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, 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. |
| POST | /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_bids | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, use the getAdvertisingEligibility method in Account API.This method allows sellers to retrieve the suggested bids for input keywords and match type. |
| POST | /ad_campaign/{campaign_id}/ad_group/{ad_group_id}/suggest_keywords | Note: This method is only available for select partners who have been approved for the eBay priority strategy program. For information about how to request access to this program, refer to Priority Strategy Access Requests in the Promoted Listings Playbook. To determine if a seller qualifies for priority strategy, 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. |
| POST | /ad_campaign/{campaign_id}/clone | 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. |
| GET | /ad_campaign | 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. |
| POST | /ad_campaign | This method can be used to create a Promoted Listings general, priority, or offsite 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.General strategy 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 general strategy campaigns, see Promoted Listings general strategy campaign flow.Priority strategy 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, priority strategy campaigns give sellers the ability to create ad groups and specify keywords to ensure their ads reach their intended audience. For more information on priority strategy campaigns, see Promoted listings priority strategy campaign flow.Promoted Offsite 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 Promoted Offsite campaigns, see Promoted Offsite.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: The user-defined campaign name The start date (and optionally the end date) of the campaign The eBay marketplace on which the campaign is hosted Details on the campaign funding modelFor details on creating Promoted Listings campaigns and how to select the items to be included in your campaigns, see Promoted Listings campaign creation. |
| GET | /ad_campaign/{campaign_id} | 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. |
| DELETE | /ad_campaign/{campaign_id} | 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. |
| POST | /ad_campaign/{campaign_id}/end | 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. |
| GET | /ad_campaign/find_campaign_by_ad_reference | This method retrieves the campaigns containing the listing that is specified using either a listing ID, or an inventory reference ID and inventory reference type pair. The request accepts either a listing_id, or an inventory_reference_id and inventory_reference_type pair, as used in the Inventory API.eBay listing IDs are generated by either the Trading API or the Inventory API when you create a listing.An inventory reference ID can be either a seller-defined SKU or inventoryItemGroupKey, as specified in the Inventory API.Note: This method only applies to the Cost Per Sale (CPS) funding model; it does not apply to the Cost Per Click (CPC) funding model. See Funding Models in the Promoted Listings Playbook for more information. |
| GET | /ad_campaign/get_campaign_by_name | 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. |
| POST | /ad_campaign/{campaign_id}/launch | This method launches a priority strategy 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. |
| POST | /ad_campaign/{campaign_id}/pause | 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. |
| POST | /ad_campaign/{campaign_id}/resume | 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. |
| POST | /ad_campaign/setup_quick_campaign | This method allows the seller to expedite the creation of a priority strategy 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 |
…(truncated)