Wishzilla API

Are you an online retailer, non-profit, or web developer and want to make it super easy for people to add wishes to Wishzilla from your website? You've come to the right place. This page includes the technical specifications for letting users add wishes from third-party websites by utilizing the Wishzilla API.

You can add wishes to Wishzilla by using a form or a link. There are several basic pieces of data you can send over, although the only required information is the title of the wish itself. But that's boring, so we wanted to make it easy for you to send over more interesting things like a description, price, URL, and image.

Using a Form

The preferred method for adding wishes to Wishzilla using the API is by using a form with a POST method. This allows the greatest level of flexibility in the data you send to us, and requires less work on your part than the link (GET) method.

So here's the basic code:


  <form action="http://www.wishzilla.com/additem.cl" method="post">

    <input type="hidden" name="api" value="1" />

    <input type="hidden" name="title" value="Wish Name" />

    <input type="hidden" name="info" value="Description of your wish" />

    <input type="hidden" name="approxPrice" value="$123.45" />

    <input type="hidden" name="netImage" value="http://yourdomain.com/images/image.jpg" />

    <input type="hidden" name="availableAt" value="http://yourdomain.com/product.htm" />

    <input type="submit" value="Add to Wishzilla" />

  </form>

You need a number of hidden fields to make the Add to Wishzilla API work correctly. Here are the details of each field.

The form action

Make sure the form action is exactly as it appears in the sample code. We do not currently require a site key, and there is no cost to utilizing the Wishzilla API. The form action must be:

http://www.wishzilla.com/additem.cl

api

The first hidden field is named "api", and must contain a value of "1".

title

The "title" field has a string value that is the title of the wish. We recommend keeping the length down to under 50 characters. There is no need to include your domain name since that information is included in the "availableAt" field. You should pass plain text without HTML, since we cannot guarantee results with HTML tags included.

info

The "info" field takes a string value that is a long description of the wish. Use line breaks (<br /> tags) instead of paragraph (<p>) tags to separate paragraphs, since Wishzilla already wraps the long description in a paragraph tag.

You can leave this field empty, in which case it simply won't be displayed.

approxPrice

This field takes a string value, so it supports more than just numbers. We did this to allow users to type things like, "Whatever you can afford," or, "$Anything." If you are passing in a currency value, make sure you include the currency marker (e.g., $123.45, not just 123.45).

netImage

This should be an absolute URL to the location of the image on your website. Supported image formats are: PNG, GIF, JPG, and TIFF. The size doesn't really matter, but if you can display it reasonably on your website it will probably work. We recommend images of 200 pixels on a side or greater. People don't like looking at tiny little postage stamp images. Wishzilla will size image down to fit, but small images are not scaled up (that would be just wrong).

When users click the "Add to Wishzilla" button, Wishzilla will pull the image from your site and store it on our servers. We do not link over to your image, so if the image changes on your site it will not update on users' wishes.

availableAt

The "availableAt" field should be filled in with the absolute URL of the product page on your site. This lets users quickly click directly to the page for that wish without having to browse or search through your site.

The Submit Button

The submit button is really the only thing users see on your site. You can style it to match your site, or you can use this image

Add to Wishzilla

along with the following code instead of the generic submit input above:


<input type="image" src="path.to.your.images/add_to_wishzillaBt.png" value="Add to Wishzilla" />

Upload the image to the appropriate location on your site; please don't link to the image on our site since it is subject to change.

The GET method using a link

Alternatively, you can place or dynamically create a link on your site that submits the wish via a GET. This is only useful if you cannot use a form for some reason. When using this method you need to make sure that all characters in the GET are valid for sending via URL. This means escaping reserved characters and dealing with nasty things like spaces. For a web-based URL encoder that seems to work pretty well, click here.

Note that the form POST method above does not require URL encoding.

Sample Link


  <a href="http://www.wishzilla.com/additem.cl?api=1&title=Wish+Name&info=Description+of+your+wish&approxPrice=%24123.45&netImage=http://yourdomain.com/images/image.jpg&availableAt=http://yourdomain.com/product.htm" >Add to Wishzilla</a>

For the valid inputs for each field, please refer to their corresponding specifications above in the form POST method.

Troubleshooting

A successful API submission will immediately add the wish to the current user's wishlist. If for some reason you get an edit wish form, this means that some portion of your submission was invalid. This is often due to a broken image link, a missing title, or an improperly encoded URL.