eBay AdCommerce is a service that allows you to promote your eBay stores and eBay listings via enhanced text integration on eBay search results pages. You can reach millions of eBay users when they are ready to buy, with a customized message targeted by keyword. You will drive more targeted visitors on your pages, giving you more opportunities to sell, and you only pay when a potential customer clicks on your link.
The AdCommerce API is an application programming interface that enables you to write your own software to utilize the eBay AdCommerce service. As either an eBay seller or a business that serves eBay sellers, you can improve the efficiency and effectiveness of your use of the AdCommerce service by building an application that is tailored to your specific needs.
This User's Guide provides the following information to help you get started with the AdCommerce API:
The AdCommerce solution contains five services, which together give you the ability to:
This section provides an overview of each of the five services provided with the AdCommerce API solution set:
Use the Campaign Service to create and modify the high-level container for your individual campaigns. Generally, campaigns group together a series of ad groups. (Ad groups are groups of ads, or creatives.) In addition, the campaign defines an overall budget, the starting and ending dates for the campaign, and the target country and language for the campaign. Currently, the API supports Keyword campaigns: you define a set of keywords that dictate when your creatives get surfaced in eBay search results.
For details on the Campaign Service calls, including the inputs and outputs for each of the call requests and responses, see the Campaign Service call reference.
The AdGroup Service creates a bucket into which you can place a set of creatives. Each ad group is associated with a set of keywords that you set up to specify when the creatives in the ad group get surfaced in eBay search results. It is important to note that both keywords and creatives are associated with an ad group independently. So, the same set of keywords can be associated with any creative in an ad group.
Although an ad group can hold up to five creatives, it is common to associate just one or two creatives with an ad group. A campaign can hold any number of ad groups, so there is no practical limit to the number of creatives that can be grouped in a single campaign. In addition to holding a set of creatives, you set a maximum cost per click (CPC) values for each ad group. By creating different ad groups with different CPC constraints, you have the ability to manage the budgets for the different groups of creatives in your campaign.
For details on the AdGroup Service calls, including the inputs and outputs for each of the call requests and responses, see the AdGroup Service call reference.
The Creative Service provides you with the means to add and modify your eBay creatives (advertisements). A creative contains a title, a first and optional second description line, a clickable URL, and an optional picture of your product. You associate your creatives with specific ad groups, which can be grouped into one or more campaigns.
Creatives are subject to guidelines that eBay has set up to ensure the user gets the best experience form the advertisements that are surfaced. In general, creatives must be concise, professional, and relevant to the related keywords. The text must be clear and truthful. Images should be pertinent and inoffensive. For complete guidelines for creating ads, see Ad Creation Guidelines in the AdCommerce online help.
For details on the Creative Service calls, including the inputs and outputs for each of the call requests and responses, see the Creative Service call reference.
Use the Keyword Service to assign specific keywords to an ad group. When you create a keyword, you can assign one or more terms to the keyword entity. In addition, you can assign up to 10,000 keywords to an ad group, with each keyword containing its own maximum CPC value and destination URL. This gives you the ability to control and fine tune how you want to target your ads.
For details on the Keyword Service calls, including the inputs and outputs for each of the call requests and responses, see the Keyword Service call reference.
Use the Report Service to create reports that describe your cost and other performance metrics per keyword. Reports help you to track the effectiveness of your campaigns and the value of your advertising budgets. Reports can include data from one or more campaigns.
For details on the Report Service calls, including the inputs and outputs for each of the call requests and responses, see the Report Service call reference.
In this use case example, Chris Hedges runs an eBay store called Max's Guitar Store that sells musical instruments and accessories. Chris wants to promote the accessory items he has in the store with AdCommerce ads. Specifically, Chris wants to promote the following:
Chris uses the AdCommerce API to create a keyword campaign, following these steps:
Chris opens an AdCommerce account through the AdCommerce web site.
Using the Campaign Service API, Chris does the following to create a campaign:
An ad group is created with the AdGroup Service API. The ad group is linked to the campaign with the campaign ID value. Once created, keywords and creatives can be linked to this ad group. Chris creates a new ad group:
Chris does the following to create a set of keywords with the Keyword Service API:
Chris generates a creative (an ad) with the Creative Service API.
A creative consists of the following data:
Once the campaign has been running for a while, Chris uses the Report Service API to periodically generate reports to track the cost for each of his keywords.
This section outlines general information that is required to work with the APIs:
All that is required to use the AdCommerce API is an AdCommerce account ID and password. Sign on and register with www.AdCommerce.com to receive your AdCommerce account information — an identification number and password. Once your ID and password are assigned, you can use them in the HTTP headers of your AdCommerce requests:
EBAY-SOA-SECURITY-USERID.
X-EBAY-SECURITY-PASSWORD.
For more information about HTTP headers, see Making a Call.
Currently, the AdCommerce API supports only keyword campaigns; it does not support category campaigns. Information about category campaigns that have been created through the AdCommerce web site cannot be retrieved or updated through the AdCommerce APIs.
Currently, eBay AdCommerce is directly supporting testing for calls to the AdCommerce API. For help testing, contact your eBay AdCommerce representative.
The AdCommerce services are not currently supported in the eBay Sandbox environment. The Production environment is preferred for testing. Because the AdCommerce API does not modify item or user data, you can safely test your application with calls to the live eBay site.
The eBay AdCommerce system limits the number of API calls to 100,000 per IP address per day across all services. Also, no advertiser can make more than five concurrent requests.
Refer to the Call References page for links to the individual AdCommerce service API call references. Each call reference includes the following information:
In addition to the call references, refer to the following links for more information about eBay AdCommerce:
© 2009 eBay Inc. All rights reserved.