Sign In
Create a FREE account
Wishpot makes it easy to:
- Share registries and wish lists
- Save money with price alerts
- Discover new products and gift ideas
- Find the best prices online
- Bookmark gift ideas as you shop
Wishpot REST API
The Wishpot REST API is an XML-based interface that gives third party developers the ability to write applications that interact with user wishlists. Before using this API, you must obtain a developer key.
The API is fully compatible with Microsoft Silverlight applications and provides an appropriate client access policy.
Getting Started
When you are assigned a development key, Wishpot provides a test server you can use while building your app. In addition to being able to create as many test users as you'd like, API calls to the test server support an additional parameter:BypassSig=1 which you can pass to bypass the
requirements to sign calls to the API. This is useful when debugging
problems that arise around generating valid signatures, and lets you
browse some of the API responses conveniently in a web browser.
Authentication and Authorization
Authentication and authorization are performed using OAuth. There are 3 urls required to complete the process of obtaining an access token. There are OAuth libraries that can be used which will simplify the authentication process, and they will require you to enter the URLs as part of their configuration.- Request Token URL: http://www.wishpot.com/api/RequestToken.ashx
(you send a request here, signed with your key, and it gives you a token back) - User Authorization URL: https://www.wishpot.com/secure/signin.aspx
(you send a user here with the token assigned in step 1) - Access Token URL: http://www.wishpot.com/api/AccessToken.ashx
(you send a request here with the original token, and exchange it for an "access" token which grants access to the user's wishlists)
When the Access Token is returned for you, you are expected to persist it and use it for future sessions involving that user. If you lose the access token, you may re-request it (by going through the steps above) and it will be re-issued.
At the conclusion of step 3, in addition to getting an access token and token secret, Wishpot also returns the user id of the user who had just authenticated, for your reference. The user id is useful for building links, in addition to making certain API calls.
When using an OAuth library, these are the standard configuration elements. For example, here is how you would set up a client using the Ruby OAuth library:
User Authentication without a browser
For all browser-based apps, the standard OAuth methods described above must be used. If you are developing a non-browser app, we do allow an alternate method of signing a user in. You may send aPOST request
to the User Authorization URL, along with the Request Token and the following additional parameters:
EmailAddress and Password. At that point, assuming authentication passes, you can request
and Authorization token. You are not permitted to store the user's credentials - you should simply store the Access Token,
as above.
Example Ruby code for logging a user in via the alternate method:
General API requirements
- All requests must be signed and include the OAuth access token as described in the OAuth spec.
- Wishpot supports all three methods for passing OAuth parameters.
- POST requests should be sent with the
Content-Type: application/x-www-form-urlencodedHTTP header.
API Overview
The Wishpot API is REST-oriented and currently models 3 resources:- User - Supports creating users, and getting information about the currently logged-in user.
- Vendor - Supports editing vendor social merchandising and product feed settings.
- List - Supports reading/adding/modifying users' lists.
- Wish - Supports reading/adding/modifying/deleting users' wishes.
- WishReserve - Supports reading the details of a wish reservation.
- WishPicture - Supports adding pictures to users' wishes.
- Category - Supports a basic, unauthenticated lookup of the list of product categories Wishpot supports.
- When creating or updating resources, parameters are all passed via
POSTrequests. When retreiving resources,GETis used. - When creating or updating resources, attributes of the resource are passed in the format
Resourcename.Propertyname. For example, to update a List's name, the parameter you would send will be labeledList.Name.
The User Resource
GET /restapi/User
Call to get details on the currently signed-in user, including all of their lists, and if the user is a vendor, information on their vendor-specific social syndication settings.
Notes:
- AccessType will be one of the following: 30 (Public), 20 (Friends Only), 0 (Private)
- The "Birthday" field will always have a year of 1800. It does not represent the person's year of birth, only the day.
GET /restapi/User/Details/{UserId *or* EmailAddress}
Returns the same as above, but for the target user. Standard privacy settings apply. You will be able to see no more and no less than the logged in user (ex. Private lists are not accessible).
Notes:- This call does not require a request or access token. However, per the OAuth spec section 9.1.1, all of the POST parameters should still be included in generating the signature. If you are on the test server, bypassing signing, the
oauth_consumer_keyis still required. - Because this call does not require a token, it can be useful for checking if a user exists before creating an account for them.
POST /restapi/User/Create
This call is used to create a user. Returns a serialized user as shown above.
Notes:- Required Parameters:
User.FirstName,User.LastName,User.EmailAddress,User.Password - Special Parameter:
User.PartnerUserId- you can pass any string or number here to represent the unique Id of the user in your system. This attribute is useful for tying users together, and is also required to make use of some whitelabel features. - You may create a user as a vendor by setting
User.IsVendorto "true". - This call does not require a request or access token. However, per the OAuth spec section 9.1.1, all of the POST parameters should still be included in generating the signature.
POST /restapi/User/Edit/{UserId}
This call is used to modify a user. It will only work for modifying the logged-in user. Attempting to modify another user will return an error.
Notes:- If you wish to convert a regular user into a vendor, set
User.IsVendorto true. - Once you set a user to be a vendor, you cannot revert that user to a non-vendor state by setting User.IsVendor to false. This will produce an error.
- You cannot edit Vendor settings using this interface. Instead, use the Vendor API.
The Vendor Resource
GET /restapi/Vendor
Call to get details on the currently signed-in user, including all of their lists, and information on their vendor settings (if the user is a vendor).
POST /restapi/Vendor/Details/{UserId *or* EmailAddress}
Returns the same as above, but for the target user. Standard privacy settings apply.
Notes:- This call does not require a request or access token. However, per the OAuth spec section 9.1.1, all of the POST parameters should still be included in generating the signature.
POST /restapi/Vendor/Edit/{UserId}
This call is used to modify a user's vendor settings. It will only work for modifying the logged-in user. Attempting to modify another user will return an error.
Notes:- This interface can only be used to set up supported feeds as specified on our help page.
- Required parameters to set up a URL feed:
User.RssFeedURL. An exception will be thrown if the update is not successful. - Required parameters to set up a FTP feed through an affiliate:
Vendor.FeedProviderId,Vendor.FeedFilePrefix. You may set one individually, but the feed will not be fully configured until both values are provided. - Accepted values for
Vendor.FeedProviderIdare as follows:- "Zoovy"
- "CJ" (for Commission Junction)
- "ShareASale"
- "GAN" (for Google Affiliate Network, and formerly Performics)
- "Mercent"
- "Linkshare"
- "PepperJam"
- You cannot use this call to turn a user into a vendor. That must be done via the User interface.
Vendor.AlertPercentDropmust be an integral value from 0 to 100. Floats or decimals are not supported.
The List Resource
GET /restapi/List/Details/{ListId}
Call to get details of the list with the provided Id. This call can be used to get the details of other user's lists as well, subject to the visibility of the logged-in user.
Notes:
- AccessType will be one of the following: 30 (Public), 20 (Friends Only), 0 (Private)
- Type is one of the following: 0 (Wishlist), 1 (Shopping List), 2 (Gift List), 3 (Pick List), 4 (Wedding Registry), 5 (Baby Registry)
POST /restapi/List/Create
This call is used to create a new list for the logged-in user. Parameters should be sent as POST variables
and the names will match the properties of the list, prefixed with the word "List". For example, to create
a new wishlist with the name "My Wishlist" for the logged-in user, send a POST containing List.Name=My Wishlist.
POST /restapi/List/Edit/{ListId}
Used to edit the properties of a given list. Paramaters are the same as the Create call.
GET /restapi/List/{ListId}/Wishes
Retrieve a list of all of the wishes on a given list.
The Wish Resource
GET /restapi/Wish/Details/{WishId}
Retrieve the details of an individual list.
Notes:
InitialPriceis the price the wish was at the time of creation.DisplayPriceis the current price of the wish, which could be user-entered.
POST /restapi/Wish/Edit/{WishId}
Edit the properties of an individual wish. Parameters should be passed as POST parameters, and they will be property names prefixed with "Wish". For
example, if you want to change the name of a wish, send a POST containing Wish.Name=My New Wish Name.
POST /restapi/Wish/Delete/{WishId}
Deletes a Wish. Attempting to delete a non-existent Wish, or the Wish of any user aside from the authenticated one will result in an error.
POST /restapi/Wish/Create
This call is used to create a new wish for the logged-in user. Parameters are the same as for the Edit call, above. Wishes can be created one of two ways:
- With a known product identifier
- Without an identifier, as completely unique, custom wishes
The first method, with an identifier, is preferable because:
- It allows you to send less data about the wish (and, presumably, allows your users to enter less data)
- Pictures, prices, etc will be managed automatically.
- Users will gain additional features like the ability to see other users wishing for the item, and possibly price alerts and price comparisons.
The following identifiers are supported:
Wish.ASIN- An Amazon.com identifier.Wish.SDCP- A Shopping.com Product IdentifierWish.SDCO- A Shopping.com Offer IdentifierWish.ProductId- A pointer to one of the other products already on Wishpot.
Required Parameters when creating a Wish:
Wish.ListId- The Id of the list the wish is being added to.Wish.Title- This is only required if the wish is being created without an identifier.
POST /restapi/Wish/Reserve
This call is used to reserve a wish for another user. There are two basic required elements - a way to identify the wish, and some representation of the reserver.
To identify the wish, one of the following is required:
Wish.Id- The Id of the wish to reserve. This is the most common mechanism.Wish.SkuandWish.PartnerUserId. For White Label customers only, this is how you can reserve one of your own user's wishes. Just send us the Id of the recipient (in terms of your Id) and the Sku of the item (in your system) and we'll look up the Wish. If there is more than one wish, we'll reserve the first one.
To identify the reserver, one of the following is required:
- A user must be logged in (ie. this call must be made with an Access Token) which will be used as the reserver
- If a user is not logged in, reservations can be made with an e-mail address:
WishReserve.ReserverEmailAddress, and preferably a friendly display name as well:WishReserve.ReserverName. When unauthenticated users make reservations, they are never surprises. Because the user is unauthenticated, the list owner will be alerted that a reservation was made, and will have the opportunity to unreserve any of the items. Also, the reserver will receive an e-mail confirmation with a special link, giving them the ability to unreserve if they change their mind. (NOTE: for White Label customers this behavior is disabled by default)
In addition to the required fields above, the following fields are optional:
WishReserve.IsSurprise- True if a wish is a surprise, false otherwise. Anonymous users will not be allowed to reserve surprise wishes. Default is false.WishReserve.Quantity- How many to reserve. Defaults to 1. If an owner is reserving their own wish, this is ignored (see below).
The response will differ depending on who is making the reservation. If the reservation is not being made by the owner on his/her own list, the response will be a WishReserve object. This is the normal case. If the reservation is being made by the owner of the wish, the response will simply be the wish. This is because, in Wishpot, we don't support a list owner making partial reservations for themselves (they can simply decrement how many they want by editing the wish). So when an owner reserves their own Wish, we mark the whole thing as reserved, and do not create separate WishReserve entities.
The WishPicture Resource
Currently, wishes support one and only one picture, and the picture is immutable once created. Eventually we hope to lift both restrictions. For now, Wish pictures can be attached to a Wish, but they cannot be removed. The only way to remove a picture is to delete and re-create the Wish.GET /restapi/WishPicture/Details/{WishPictureId}
Retrieve the details of an individual wish picture.
POST /restapi/WishPicture/Create
Creates a Wish Picture. Follows the same conventions described at the beginning of this document.
Notes:
WishPicture.RemoteUrl#,WishPicture.Width#,WishPicture.Height#- these fields represent versions of the same image in different sizes. We support up to 3 sizes for a given image. If you have only one version, just fill in the first set of parameters (# = 0).- Required Fields:
WishPicture.WishId- The ID of the wish to assign the picture to. Must belong to the logged-in user, and must not already have a picture.WishPicture.RemoteUrl0,WishPicture.Width0,WishPicture.Height0OR you can upload an image by passing a binary image in theWishPicture.Imageparameter inmultipart/form-dataformat (similar to Twitter'supdate_profile_imageAPI call).
The WishReserve Resource
This is a (currently read-only) representation of a wish reservation.GET /restapi/WishReserve/Details/{WishReserveId}
The Category Resource
The category resource supports a single lookup with no authentication required, so it's linked here:GET /restapi/Category/
This is useful when creating wishes because, if you use a category name as one of the wish's tags, we'll automatically include the wish in that category.
This list is added to on a regular basis.
Error Responses
When errors occur in the processing of operations to the API, an appropriate 4xx or 5xx HTTP Status code will be returned. A program-readable error will be serialized as follows:
There are a few response codes, which you can rely upon in your code.
| Code | Meaning |
|---|---|
| 3020 | You attempted to create a user with an e-mail address that already exists in Wishpot, using a password that didn't match their Wishpot password. |
Troubleshooting
- I'm getting SSL Certificate Errors on the test server, what is wrong?
- Currently our test-server has a self-signed certificate, however that won't be an issue in production. For the test server, please disable certificate validation when making API calls (most languages/libraries provide support for this)
- I have a Request token, but I get an error when trying to exchange it for an Access token
- This usually means the user has not authenticated with Wishpot, giving you permission to access their account. It is that process that allows a Request token to be exchanged for an Access token. If you're creating users yourself, you should take a look at the User Authentication without a Browser process above to do this on their behalf.
