If you are a vendor or a potential vendor, you will want to give wines.com an XML feed that matches our specification. An example is worth more than an explanation so let's get to it.
The following is an example XML file with only one Item in it. The important things to note here :
<?xml version="1.0" encoding="UTF-8"?> <Items> <Item> <sku>12345</sku> <upc>5449010294</upc> <name>2007 John Doe Winery Special Reserve Napa Valley Chardonnay 750ml</name> <brand>Special Reserve</brand> <manufacturer>John Doe Winery</manufacturer> <varietal>Chardonnay</varietal> <vintage>2007</vintage> <country>United States</country> <region>California</region> <subregion>Napa Valley</subregion> <appellation></appellation> <sub-appelation></sub-appelation> <size>750ml</size> <food-pairing>red snapper, beef or buffalo, lasagna, red wine sauces</food-pairing> <industry-reviews> <industry-review> <industry-review-detail> <![CDATA[This 2007 wine is completely fictitious. But for a fictitious wine, it has an excellent bouquet. This wine is only used as an example to further your understanding of the API. Notice the use of CDATA tags to escape any paragraph style data. This is important!]]> </industry-review-detail> <industry-review-by>ws</industry-review-by> <industry-review-points>95</industry-review-points> </industry-review> </industry-reviews> <regular-price>129.00</regular-price> <price>109.99</price> <six-pack-price></six-pack-price> <case-price>1156</case-price> <on-sale>false</on-sale> <on-sale-price></on-sale-price> <free-shipping>false</free-shipping> <special-offer><![CDATA[buy a case and get free ground shipping in the continental US]]></special-offer> <out-of-stock></out-of-stock> <special-designation>organic</special-designation> <description> <![CDATA[This 2007 wine is completely fictitious. But for a fictitious wine, it has an excellent bouquet. This wine is only used as an example to further your understanding of the API. Notice the use of CDATA tags to escape any paragraph style data. This is important!]]> </description> <tasting-notes> <![CDATA[This 2007 wine is completely fictitious. But for a fictitious wine, it has an excellent bouquet. This wine is only used as an example to further your understanding of the API. Notice the use of CDATA tags to escape any paragraph style data. This is important!]]> </tasting-notes> <label-image-thumbnail-url>http://www.examplemerchantstore.com/product_images/93833t.jpg</label-image-thumbnail-url> <label-image-url>http://www.examplemerchantstore.com/product_images/93833.jpg</label-image-url> <bottle-image-thumbnail-url></bottle-image-thumbnail-url> <bottle-image-url></bottle-image-url> <purchase-url>http://www.examplemerchantstore.com/wineproduct.php?pf_id=93833</purchase-url> <tags>bold, light, fruity, smooth</tags> </Item> </Items>
Fields highlighted by bold text are required. If data is not provided in these required fields, the wine listing you provided will not be "searchable" through the Wines.com system - it will not display in the search results index or on a wine landing page.
| sku | the unique part number identifier for this wine |
| upc | the unique UPC number for this wine |
| name | name of the wine |
| manufacturer | the maker of this wine or name of the winery |
| brand | aproprietary brand name specific to this wine |
| varietal | type of grape or blend of grapes - this area also includes "designations" for Chianti Classico, Bordeaux Blend, White Blend, Burgundy Blend, etc. |
| vintage | year only please. Nothing in this field will mean it is Non-Vintage |
| country | country of origin of this wine - we use the same country spellings as the TTB: http://www.ttb.gov/importers/ |
| region | usually a state, province or general area of a country (e.g. California, Bordeaux) |
| subregion | an area within a region (e.g. Sonoma County, Graves) |
| appellation | next level of specificity down after subregion; but, sometimes used as a subregion (e.g. Russian River Valley, Graves de Vayres) |
| sub-appelation | next level of specificity down after appellation; but, sometimes used as appellation |
| size | bottle size |
| food-pairing | text describing the food pairing; often a recipe by name (e.g. Roast Leg of Lamb with Mushroom Wild Rice) |
| industry-review-detail | text in paragraph form summarized from the actual wine review (use CDATA here to protect special characters) |
| industry-review-by | who gave the point rating or award (e.g. Robert Parker) |
| industry-review-points | usually listed in points out of 100 (e.g. 91 Points); can also be a "tasters choice, festival winner or gold medal winner) |
| regular-price | typical street price or MSRP |
| price | the price at which you are actually selling the wine |
| six-pack-price | price for 6 bottles of this wine |
| case-price | price for 12 bottles of this wine |
| on-sale | is the wine on sale (value of yes or no) |
| on-sale-price | on sale price of the item. Wines.com will figure and display savings percentages of sale |
| free-shipping | is the item up for free shipping (value of yes or no) |
| special-offer | 100 character description of the special offer, “buy a case and get free shipping”… |
| out-of-stock | is this wine listing in stock (value of yes or no) |
| special-designation | must be one of these designations only – if more than one separate by comma. (e.g. organic, collectible, sweet-wine, kosher, screw-cap, half-bottle) |
| description | the full description of the wine in this listing (use CDATA here to protect special characters) |
| tasting-notes | provided from a review by the wine maker or other expert - often used as the whole description (use CDATA here to protect special characters) |
| label-image-thumbnail-url | URL on your site to find where the label-thumbnail image is stored |
| label-image-url | URL on your site to find where the label-image is stored |
| bottle-image-thumbnail-url | URL on your site to find where the bottle-thumbnail-image is stored |
| bottle-image-url | URL on your site to find where the bottle-image is stored |
| purchase-url | the URL that is used to get to this wine’s page to purchase it from the vendor (merchant or seller) store |
| tags | descriptive word or words separated by comma (e.g. light & fruity, smooth, supple, earthy, spicy, big and bold) - we do not use "white" or "red" here... |
There are many ways to check this. One of the easiest ways is to open your feed in Firefox or Internet Explorer. Both of these browsers have simple validations that might help you to detect issues in your feed before you submit it to us.
If you have a Unix, Linux or OSX system, you may alternatively use the free utility xmllint to validate your data. More information on the xmllint utility here.
If you have any special characters in your data, proper XML usage is to encapsulate that data in a Character Data tag, or a CDATA tag. More information on what a CDATA tag is here.
This is the most common issue we have with new feeds. Many wines and wine data has diacritics, special characters, accents "smart" quaotes, and the occasional umlaut. Sometimes this passes by without notice. Other times it throws the entire feed off. Wines.com does it's best by attempting to convert this information to UTF-8 for you. But some things still slip through the cracks sometimes. This is why it is best that you do this yourselves. There is a special command line utility for this called 'iconv' that is available for all unix, linux and osx systems that may help you.
You can find out more about UTF-8 here