The LinkShare Coupon Web Service gives you easy access to coupon and promotional link data for your advertisers. All of the links are reviewed by LinkShare to ensure that they are indeed coupon or consumer promotional links. To receive this creative, you simply place a REST-based Web Services call with your feed token. (For a PDF of these guidelines and an XML schema, please click here: , or see the attachment at the end of the article.)

Before using the Coupon Web Service, you must apply and be approved. Applying is easy: From the Publisher Dashboard, click Links > Web Services > Coupon Web Service, and then click Apply.

Submitting a Coupon Web Service Request
A REST-based Web Service lets you request a feed using a query structured like an HTML GET. The inputs to the query are your Web Services token, the product category, the promotion type, the network, and an advertiser ID (MID). Your Web Services token is required; the other values are optional.

Here is a sample request that excludes MID:

http://feed.linksynergy.com/coupon?token=94e973c41fe2c696de23a111b91b6182ae73cf3ee4dddb0eefa0091c266cc5ea&category=4169&promotiontype=21&network=1

This query will send coupon and promotional link data for all the advertisers you are partnered with in network 1 who have products in category 4169 that correspond with offer-promotion type 21.

Name-Value Pairs

Publisher Token:[token=94e973c41fe2c696de23a111b91b6182ae73cf3ee4dddb0eefa0091c266cc5ea]
This is the Web Services token that is generated on the Web Services page of the Publisher Dashboard under the Links tab. It is used to authenticate publishers and must be submitted with your query.

Category: [category=4169]
This variable may contain one or more valid category IDs. These IDs are assigned by LinkShare. For a list of category IDs, please click here. In addition, a Web Services method for obtaining valid category IDs is described below. Category is an optional variable. If you do not submit it, your query will search all categories.

Promotion Type: [promotiontype=21]
This variable may contain one or more valid promotion type IDs. For a list of promotion type IDs, please click here. In addition, a Web Services method for obtaining valid promotion type IDs is described below. This is an optional variable. If you do not submit it, your query will search all promotional types.

Network: [network=1]
This variable may contain one or more network IDs. This is an optional variable. If you do not submit it, your query will search all the LinkShare Networks.

Network	Network ID
US	1
UK	3
CAN	5

MID: [mid=36518]

This variable may contain one or more Advertiser ID values. To retrieve Advertiser MIDs from the Publisher Dashboard, select Links, then click Get Links and an advertiser's name, lastly click Advertiser Info at left. This is an optional variable. Use it to limit your query to specific advertisers. If you do not include it, your query will search all advertisers.

Submitting Queries with Multiple Values
You can place multiple values in all query string variables, except for 'token=', by delimiting the values with a pipe character '|'. Multiple values passed within one variable are treated as an OR condition. For example, 'category=1|2|3' sends links from categories 1 or 2 or 3.

Multiple query string variables themselves are treated as an AND condition. For example 'category=2&network=1|3' sends coupon and promotional link data for all category 2 links that are in network 1 or 3.

Here is a sample request with multiple values in some of the variables:

http://feed.linksynergy.com/coupon?token=94e973c41fe2c696de23a111b91b6182ae73cf3ee4dddb0eefa0091c266cc5ea &category=983|341|907&promotiontype=64|22|97&network=1|3

This query will send coupon and promotional link data for advertisers you are partnered with in network 1 or 3 who have products in categories 983, 341, or 907, that fall under offer-promotion type 64, 22, or 97.

Sample Response
This sample response returned a 15 percent-off coupon for new customers on a product in the computer category from an advertiser in the LinkShare Network.

<?xml version="1.0" encoding="UTF-8"?>
<couponfeed>
   <link type="TEXT">
      <categories>
         <category id="983">computers</category>
         <category id="12">electronics</category>
         <category id="14">gifts</category>
      </categories>
      <promotiontypes>
         <promotiontype id="22">percentage off</promotiontype>
      </promotiontypes>
      <offerdescription>15 percent off</offerdescription>
      <offerstartdate>2009-04-01</offerstartdate>
      <offerenddate>2009-05-31</offerenddate>
      <couponcode>KJEISLD</couponcode>
      <couponrestriction>New Customers Only</couponrestriction>
      <clickurl>http://click.linksynergy.com/fs-bin/click?id=XXXXXXXXXXX&offerid=164317.10002595&type=4&subid=0</clickurl>
      <impressionpixel>http://ad.linksynergy.com/fs-bin/show?id=XXXXXXXXXXX&bids=164317.10002595&type=4&subid=0<impressionpixel>
      <advertiserid>000</advertiserid>
      <advertisername>Sample Advertiser Name</advertisername>
      <network id="1">Linkshare Network</network>
   </link>
</couponfeed>

Note that each link is wrapped in <link></link> tags. LinkShare may categorize each link with one, two, or three <category> or <promotiontype> values. For example, a link to a coupon for a computer might be categorized under computers, electronics, and gifts. If a link has categories or promotion types other than the ones you searched for, the corresponding category names and IDs are displayed, as the example above shows with <category id="12">electronics</category>and <category id="14">gifts</category>. Appendix 1 provides definitions for all of the elements that may appear in the response.

In addition, the <offerenddate>may contain the word 'ongoing', instead of a date value.This indicates that the advertiser has not yet determined an end date for their coupon.

Several publishers have expressed interest in creating a unique ID for each link. This can be done by extracting the <advertiserid> value and the 'link type' and 'link id' values from the <clickurl> string. The 'link id' is the number that follows the period in the 'offerid'. Here's an example drawn from the sample response above with these values in red: 

<advertiserid>000</advertiserid>

<clickurl>http://click.linksynergy.com/fsbin/click?id=XXXXXXXXXXX&offerid=164317.10002595&type=4&subid=0</clickurl>

The advertiserid value is 000, the link type value is 4, and the link id is 10002595, making the unique ID for this link: 000_4_10002595.

Obtaining Numbers for Categories, Promotion Types, and Network Values
To obtain numbers for categories, promotion types, and network values, send a request with just your Web Services token and 'promocat=1'. Here's a sample request:

http://feed.linksynergy.com/coupon?token=94e973c41fe2c696de23a111b91b6182ae73cf3ee4dddb0eefa0091c266cc5ea&promocat=1

Let's say there is only one LinkShare Network active for Coupon Web Services (US) and you are in it. And let's say there are only two categories (Books and Baby & Nursery) and two promotion types (free shipping and percentage off). The response to the request above would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<couponfeed>
   <network id="1">
      <name>LinkShare Network</name>
      <categories>
         <category id="402">books</category>
         <category id="4169">baby & nursery</category>
         <category id="4169">baby & nursery</category>
      </categories>
      <promotiontypes>
      <promotiontype id="402">freeshipping</promotiontype>
      <promotiontype id="21">percentage off</promotiontype>
      </promotiontypes>
   </network>
</couponfeed>

The values in the sample response above indicate that to restrict your request to advertisers in the LinkShare network, it should include 'network=1'. To restrict your request to the 'books' category, your request should include 'category=402'. And to restrict your request to free-shipping promotion types, it should include 'promotiontype=402'.

Note: the numbers used in this example will differ from the results you receive. Please use the results you receive when creating your queries.

Error Handling
There are five error responses:

1. Internal Error

<?xml version="1.0" encoding="UTF-8"?>
<fault>
   <errorcode>10</errorcode>
   <errorstring>Internal Error Unable To Process Request At This Time</errorstring>
</fault>

2. Web Services token invalid or not approved for coupon feed

<?xml version="1.0" encoding="UTF-8"?>
<fault>
   <errorcode>20</errorcode>
   <errorstring>Access Denied Token ID Is Invalid or Not Approved for Coupon Feed</errorstring>
</fault>

3. Usage limited to 50 calls per GMT day

<?xml version="1.0" encoding="UTF-8"?>
<fault>
   <errorcode>30</errorcode>
   <errorstring>Usage Quota Exceeded</errorstring>
</fault>

4. Invalid or missing parameters

<?xml version="1.0" encoding="UTF-8"?>
<fault>
   <errorcode>40</errorcode>
   <errorstring>Invalid Request</errorstring>
</fault>

5. No matching data for the request

<?xml version="1.0" encoding="UTF-8"?>
<fault>
   <errorcode>50</errorcode>
   <errorstring>No Matching Data</errorstring>
</fault>

Appendix 1

This table provides descriptions of all the elements that may appear in a response.

Element	Description
<category>	A required field. Each coupon may be grouped into 1, 2, or 3 product categories.
<promotiontype>	A required field. Each coupon may be grouped into 1, 2, or 3 promotion types.
<offerdescription>	A required field. It provides the details of the coupon; for example, 15% off.
<offerstartdate>	A required field. It provides the coupon's start date.
<offerenddate>	A required field. It provides the coupon's end date and may contain the word 'ongoing' indicating that the advertiser has not yet determined the coupon's end date.
<couponcode>	An optional field. It will only appear when an advertiser requires customers to input a code to use a coupon.
<couponrestriction>	An optional field. It will only appear with coupons the advertiser has placed a restriction on; for example, "new customers only."
<imageurl>	An optional field. It will only appear when your search returns banner links, i.e., when the response includes <link type="BANNER">.
<clickurl>	A required field. It provides the link to the coupon that you will put on your site.
<impressionpixel>	An optional field. It is a 1x1 pixel for tracking impressions and will be included for all text links (when the response includes <link type="TEXT">), but not for all banner links (<link type="BANNER">).
<advertiserid>	A required field. It provides the ID of the advertiser offering the coupon.
<advertisername>	A required field. It provides the name of the advertiser offering the coupon.
<network>	A required field. It provides the network—U.S., U.K., or Canada—that the advertiser is in.