Wishpot API

wishpot edited this page Feb 20, 2012 · 128 revisions
Clone this wiki locally

The Wishpot REST API is an XML-based interface that gives third party developers the ability to write applications that interact with user wishlists and vendor product lists. Before using this API, you must obtain a developer key (e-mail developers@wishpot.com). We have a some code samples on GitHub to get you started. Need help? Please post in our new developer forum.

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. For help in testing the signing process, there is a helpful javascript-based signature generator here.

Authentication and Authorization

Authentication and authorization are performed using OAuth. There are 3 urlsrequired 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.

  1. 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)
  2. User Authorization URL: https://www.wishpot.com/secure/signin.aspx
    (you send a user here with the token assigned in step 1)
  3. 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:

@consumer=OAuth::Consumer.new( "yourpublickey", "yourprivatekey", {
:site=>"http://www.wishpot.com/",
:request_token_path=>"/api/RequestToken.ashx",
:access_token_path=>"/api/AccessToken.ashx",
:authorize_url=>"https://www.wishpot.com/secure/signin.aspx"
})

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 a POST 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:

request_token = @consumer.get_request_token
@consumer.request(:post,  request_token.authorize_url, nil, {}, {'EmailAddress'=>'user@mail.com', 'Password'=>'secretword'})
access_token = request_token.get_access_token

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-urlencoded HTTP header.

API Overview

The Wishpot API is REST-oriented and currently models the following resources:

  1. User - Supports creating users, and getting information about the currently logged-in user.
  2. UserPicture - Supports adding/changing/removing a users' photo.
  3. Vendor - Supports editing vendor social merchandising and product feed settings.
  4. List - Supports reading/adding/modifying users' lists.
  5. Wish - Supports reading/adding/modifying/deleting users' wishes.
  6. WishReserve - Supports reading the details of a wish reservation.
  7. WishPicture - Supports adding pictures to users' wishes.
  8. Category - Supports a basic, unauthenticated lookup of the list of product categories Wishpot supports.
  9. Product - Supports read-only operations on products.
  10. ProductPicture - Supports reading/adding/editing/deleting the pictures associated with a product.
  11. ShippingPolicy - Supports creating/editing the shipping policies of different products.
  12. Purchase - Supports reading and editing the details of a purchase of a product
  13. UserMessage - Supports creation/sending of messages.
  14. UserMailbox - Reading and filtering of items in a users mailbox, as well as editing mailbox items.
  15. OAuthCredential - Supports creating/editing a user's OAuth credentials with other systems (Facebook, Twitter).
  16. PaypalCredential - Supports creating/editing a user's Paypal account.
  17. Follow - Supports creating/deleting relationships where a user follows another user, as well as viewing who a given user is following or followed by.
  18. MerchantClick - Supports read-only reporting on outbound clicks on products. Vendors and Partners can see traffic sent to them.
  19. PriceDrop - Supports read-only reporting on price drops we've tracked on vendor items.
  20. UserDevice - Supports creating/editing devices on which a user will receive push notifications.
  21. Report - Supports running various partner reports.

There are a number of conventions used throughout the API:

  1. When creating or updating resources, parameters are all passed via POST requests. When retreiving resources, GET is used.
  2. 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 labeled List.Name.
  3. Many Resources have a LastModifiedTime and/or a CreatedTime property. These properties are always in UTC, and they're always read-only. The system sets them automatically.

The User Resource

GET /restapi/User

>> Example Output << 

Call to get details on the currently signed-in user, and if the user is a vendor, information on their vendor-specific social syndication settings.

  • 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.
  • If you wish to convert a regular user into a vendor, set User.IsVendor to 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.

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_key is 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.IsVendor to "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

This call is used to edit a user. Returns a serialized user as shown above.

GET /restapi/User/Search

Allows you to search for users with the following parameters:

  • SearchTerm - Either an email address, name, or screenname

Notes:

  • Returns results in the exact same format as the /restapi/User/ call, above
  • Authentication is not required for this call.
  • This call is limited to 25 results. If you want to continue iterating, you can page through results by passing a Pg parameter - ex Pg=2.

GET /restapi/User/Experts

Allows you to retrieve a list of users marked as experts by the calling partner. Their most recent wishes will also be returned.

Notes:

  • Authentication is not required for this call.

Optional Paramaters:

  • Limit - The maximum number of results to return. Defaults to 25. Maximum is 50.
  • Pg - Defaults to 1. Used in tandem with Limit to advance through multiple pages.
  • RandomSort - Defaults to false. If set to true, Page value is ignored, since paging will not work.
  • ListType - Allows you to restrict the most recently returned wishes to a those on a certain list type. (List Type options are described in the List Resource) If not specified, the recent wishes will be from all types of lists.
  • NumWishes - Defaults to 4. If set to 0, no recent wishes will be returned. Maximum value of 25.

GET /restapi/User/Feed/{UserId}

This returns an (Activity Streams)[http://activitystrea.ms/] formatted version of the given user's activity (/Feed/) or of their friends' activity (/FriendFeed/). If you want to show the user interesting news, that would be /FriendFeed/. If you want to show both the user's activity and their friend's activity in one feed, you can use /FullFeed/.

Optional Paramaters:

  • Limit - The maximum number of results to return. Defaults to 100.
  • Pg - Defaults to 1. Used in tandem with Limit to advance through multiple pages.

In addition to the standard format, we've added some extra attributes to make the document a bit more structured. These attributes are in the Wishpot namespace, and prefixed with wp:

    <entry wp:type="2" wp:type-name="NewWish" wp:source-object-id="619518">
        <id>39213</id>
        <title type="text">Tom wished for Glass Square Storage Bowls &amp; Lids Set/3</title>
        <updated>2011-11-12T04:35:28-08:00</updated>
        <author wp:id="14435">
            <name>Tom</name>
            <uri>http://tom.test.wishpot.com/user/14435</uri>
            <link rel="preview">http://tom.test.wishpot.com/pix.axd?h=75&amp;w=75&amp;uid=14435</link>
        </author>
        <content type="text"></content>
        <activity:verb>save</activity:verb>
        <activity:object wp:vendor-id="19361">
            <id>529204</id>
            <title>Glass Square Storage Bowls &amp; Lids Set/3</title>
            <object-type>product</object-type>
            <link rel="alternate" type="text/html">http://tom.test.wishpot.com/public/products/?pid=529204</link>
            <link rel="preview">http://tom.test.wishpot.com/pix.axd?h=100&amp;w=100&amp;pid=529204</link>
        </activity:object>
    </entry>

The extensions are:

  • wp:id - Tells you the user id of the author of the activity
  • wp:type and wp:type-name tell you what type of story this is, using Wishpot's own terminology instead of relying simply on the standard verbs. You can filter on these story types by passing a parameter called EventType with a comma separated list of integers (ex. ?EventType=1,4,5). The current types are:
    • NewFriend=1
    • NewWish=2
    • NewWishComment=3
    • NewProductReview=4
    • NewAlert=5
    • NewList=6
    • VendorPriceDrop=7
    • NewFollower=8
    • NewPurchase=9
  • wp:source-object-id - Tells you the id of the object that is primarily responsible for this entry in the newsfeed. In general, if this object were to be deleted, so would the story. If this object were to have it's privacy changed, so would the story. In most cases, this object is already part of the story. For example, if it's a story about a new follower, this will simply be the Id of the follower. However, other times the object is not part of the story. For example, if it's a new purchase, this is the purchase id - the story itself describes the buyer, seller, and product.

GET /restapi/User/{UserId}/Friends

This call returns a list of all the given user's friends. You can also drop the "UserId" to get a list of the currently logged-in user's friends. Friends are rendered simply as a collection of users.

GET /restapi/User/{UserId}/Following

This call returns a list of everyone the given user is following. You can also drop the "UserId" to get a list of who the currently logged-in user follows. This is rendered simply as a collection of users with pictures.

GET /restapi/User/{UserId}/Followers

This call returns a list of everyone who follows the given user. This is rendered simply as a collection of users with pictures.

GET or POST /restapi/User/FindFriendsFrom/{SocialNetwork} or Email

This call finds users on the platform who are friends with the currently logged-in user on a different social network. Valid values for SocialNetwork are Twitter or Facebook. This call will not return people who are already friends, or who the user is already following, so that it's useful for friend discovery.

If you want to find friends based on e-mail address (ex. uploading a contact list) you can call /FindFriendsFrom/Email and pass in a single parameter: EmailAddresses with a comma-separated list of e-mail addresses.

GET /restapi/User/{UserId}/Lists

This call returns a list of all the given user's lists. You can also drop the "UserId" to get a list of the currently logged-in user's lists.

The UserPicture Resource

Currently, a user supports one and only one picture.

>> Example Output << 

GET /restapi/User/UserPicture/Details/{UserPictureId}

Retrieve the details of an individual UserPicture.

GET /restapi/User/UserPicture/Index/

Retrieve the details of the logged in user's UserPicture.

POST /restapi/User/UserPicture/Create

Creates or update the UserPicture for the currently logged in user. Follows the same conventions described at the beginningof this document.

Notes:
  • UserPicture.RemoteUrl#, UserPicture.Width#, UserPicture.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:
    • UserPicture.RemoteUrl0, UserPicture.Width0, UserPicture.Height0 OR you can upload an image by passing a binary image in the UserPicture.Image parameter in multipart/form-data format (similar to Twitter's update_profile_image API call).

POST /restapi/User/UserPicture/Delete

Deletes the UserPicture of the currently logged in user.

The Vendor Resource

GET /restapi/Vendor

>> Example Output << 

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 parameter to set up a URL feed: Vendor.RssFeedURL. An exception will be thrown if the update is not successful.
  • Required parameter to set up a FTP feed through an affiliate: Vendor.FeedFilePrefix. You may set one individually, but the feed will not be fully configured until both values are provided.
  • Both types of feeds also require a Vendor.FeedProviderId. Accepted values are:
    • FTP/API-based feeds (require a FeedFilePrefix):
      • "Zoovy"
      • "CJ" (Commission Junction)
      • "ShareASale"
      • "GAN" (for Google Affiliate Network, and formerly Performics)
      • "Mercent"
      • "Linkshare"
      • "PepperJam"
      • "Zanox"
      • "ImageKind"
      • "AffiliateWindow"
      • "GoogleMerchant" (for Google Merchant Center)
      • "CafePress"
    • URL-based feeds (require an RssFeedURL)
      • "Versafeed"
      • "Bonanza"
      • "UlitmateFeed"
      • "RSS" (for Google Base-formatted RSS)
  • You cannot use this call to turn a user into a vendor. That must be done via the User interface.
  • You may not enabled auto-posting to a Facebook wall via the API, since the user needs to provide explicit permission through Facebook Connect.
  • Vendor.AlertPercentDrop must be an integral value from 0 to 100. Floats or decimals are not supported.

The List Resource

GET /restapi/List/

With no path/arguments, returns a summarized list of all of the logged-in user's lists

>> Example Output << 

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), 6 (Product List)

GET /restapi/List/Search

Allows you to search for lists with the following parameters:

  • List.LastName (required) - The Last Name of the list owner. Partial matches are supported, but this must not be empty.
  • List.FirstName - First Name of the list owner. Optional, and partial matches are supported.
  • List.Type - List Type to filter on. Optional, types listed above (0 = Wishlist, etc)

Notes:

  • Returns results in the exact same format as the /restapi/List/ call, above
  • Authentication is not required for this call.
  • This call is limited to 25 results. If you want to continue iterating, you can page through results by passing a Pg parameter - ex Pg=2. The default is one.

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.

>> Example Output << 

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. Required argument:List.Type

POST /restapi/List/Edit/{ListId}

Used to edit the properties of a given list. Paramaters are the same as the Createcall.

GET /restapi/List/{ListId}/Wishes

Retrieve a list of all of the wishes on a given list.

The Wish Resource

A Wish is an instance of a Product on a List.  A Wish is always on a List, and always refers to a Product.  A user can have multiple wishes for the same product if they prefer, but this is generally only if they want to put the same product on multiple lists.  If they want more than one of a given product, they'll create a single wish but increment it's QuantityDesired.

>> Example Output << 

GET /restapi/Wish/Details/{WishId}

Retrieve the details of an individual wish.


Notes:

  • Price is the read/write price that a user can choose for a Wish.  It is the only price that is explicitly settable on the Wish resource.
  • InitialPrice is the price the wish was at the time of creation, and is read-only.  It's used only as a matter of historical record for keeping track of how the price has changed since it's creation.
  • DisplayPrice is the definitive price that should be shown in User Interfaces.  It will return the Price, if present.  Otherwise, will fall-back to displaying the product's price.

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:

  1. With a known product identifier
  2. 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:

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/Share/{WishId}

This call is used to share a user's wish on a social network.

Required Parameter:

  • SocialNetwork - Can either be Twitter or Facebook, which is passed as ?SocialNetwork=Facebook.

Optional Parameter:

  • Body - The user's comment or text to be included with the post. For Twitter, we will automatically generate a bit.ly link to the URL for the wish. Please allow 15 characters of the 140 maximum for the link. Otherwise, the message will be truncated.

Notes:

  • In order for this operation to succeed, the user must already have a stored OAuthCredential for the provided social network.
  • To share on Facebook, publish_stream permission must have been obtained.

POST /restapi/Wish/Search

[NOTE: Currently Disabled, to return in the Future. Use Product Search instead]

This call is used to search wishes, and it can be done across multiple lists and users if necessary.

This call requires at least one search filter. A search filter is comprised of

  1. UserId - The Id of the user to search. Required
  2. ListIds - Comma-seperated list of list ids (which belong to the user, above). Optional.
  3. Tags - Comma-seperated list of tags to filter on. Optional.

Optional Paramaters

  • SearchTerm - A word to search all of the wishes that meet the search filters' criteria (above)
  • Limit - The maximum number of results to return. Defaults to 25. Maximum is 50
  • Page - Defaults to 1. Used in tandem with Limit to advance through multiple pages.

Here is a sample request with multiple search filters, and a search term:
http://www.wishpot.com/restapi/Wish/Search?Filter=UserId=588&Filter=UserId=23380;Tag=Televisions&SearchTerm=Panasonic
(note, for clarity this isn't escaped, but because the filters can include equals signs, ampersands, etc. they need to be escaped)

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:

  1. Wish.Id - The Id of the wish to reserve. This is the most common mechanism.
  2. Wish.Sku and Wish.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:

  1. A user must be logged in (ie. this call must be made with an Access Token) which will be used as the reserver
  2. 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).
  • WishReserve.PartnerPurchaseId - If you want to tie this reservation to a shopping cart receipt id or Point Of Sale system, you can log an id with this reservation.

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.

>> Example Output << 

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 beginningof 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.Height0 OR you can upload an image by passing a binary image in the WishPicture.Image parameter in multipart/form-data format (similar to Twitter's update_profile_image API call).

The WishReserve Resource

This is a (currently read-only) representation of a wish reservation.

GET /restapi/WishReserve/Details/{WishReserveId}

<WishReserve xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wishpot.com/restapi">
  <Id>3248</Id>
  <ReserverUserId>14464</ReserverUserId>
  <TargetUserId>14463</TargetUserId>
  <TargetWishId>217621</TargetWishId>
  <Quantity>1</Quantity>
  <IsSurprise>false</IsSurprise>
  <Price xsi:nil="true"/>
  <NumReturned>0</NumReturned>
  <ReservedTime>2008-12-18T01:45:31.39</ReservedTime>
</WishReserve>

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.

The Product Resource

A product has a one-to-many relationship with Wishes. Every Wish has a Product that it refers to.  A Product may or may not also have a related Vendor.  If it does, that means the Product is sold by the Vendor, and the Vendor has permission to modify the product.

>> Example Output << 

GET /restapi/Product/Details/{ProductId}

Retrieve the details of an individual product. A product is a single instance in the catalog, which multiple people may have created wishes for.

If you are logged in as a user, a summary of your wishes for the product will also be included.

>> Example Output << 

POST /restapi/Product/Purchase/{ProductId}

This call is used to create a Purchase for an product.

Notes:

  • The product for sale must have a price and a vendorId associated with it.
  • You must be logged in as the seller (the vendorId of the Product), or as an administrator of the seller's account in order to create a purchase record.

Optional Fields:

  • Purchase.AccessType Supported values are "0" for Private, and "30" for Public (default).
  • Purchase.Status Supported values are "0" for Cancelled, "1" for Complete (default), and "2" for Pending
  • Purchase.ViewerBuyerUserId Set the ID of the buyer.
  • Purchase.Price Use to override the cost of the product.
  • Purchase.CurrencyIsoCode Use to override the currency of the product.

POST /restapi/Product/Search

This call searches products. It follows the conventions described in the Search Results section, below.

Parameters for Filtering:

  • OutOfStock - Set to "true" if you'd prefer to include out of stock items in the response. Default is false.
  • MinPrice - The minimum price of an item you want to show
  • MaxPrice - The maximum price of an item you want to show
  • CategoryId - The category of item to filter on. Category id's are provided in the returned refinements/segments, and the full list of Categories is accessible via the Category resource.
  • VendorId - Set to a given vendor's id if you only want to see products sold by this vendor

Parameters for Sorting: This is passed in in the format "Sort=" followed by an HTTP-escaped sort definition.

  • Price=ASC or DESC ex. Sort=Price%3DASC
  • CreatedTime=ASC or DESC
  • Location=Lat,Long

Notes:

POST /restapi/Product/Browse

This call returns the exact same format as Product/Search however it doesn't require any parameters. It's simply used as a way to browse popular products. It supports basic paging and limiting, but doesn't support the full array of filters that product search does.

POST or GET /restapi/Product/Find

Unlike Search, Find is used to find exactly one product. It takes the same parameters as Edit does, but uses those parameters to look up a product instead of edit one. This is useful because products tend to have a lot of candiate keys. For example:

  • You can pass in Product.VendorId and Product.Sku to find a given vendor's product
  • You can pass in Product.Url and Product.Upc or Product.Sku to find a product with that Upc/Sku if there's a vendor who's domain matches that of the Url.

This is useful in cases when you know a precise Product is in the Wishpot system, but you don't know what it's ProductId is.

Sub-Resource: Shipping Policies

POST /restapi/Product/{ProductId}/ShippingPolicies

This call lists all of the Shipping Policies for a product.

POST /restapi/Product/{ProductId}/ShippingPolicy/Create

Use this call to create a Shipping Policy for a product.

Sub-Resource: Product Pictures

POST /restapi/Product/{ProductId}/ProductPictures

This call lists all of the Product Pictures for a product.

POST /restapi/Product/{ProductId}/ProductPicture/Create

Use this call to create a Product Picture for a product.

Notes:

  • ProductPicture.RemoteUrl#, ProductPicture.Width#, ProductPicture.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).
  • You must be logged in as the seller (the vendorId of the Product), or as an administrator of the seller's account in order to create a ProductPicture.

Required Fields:

  • ProductPicture.RemoteUrl0, ProductPicture.Width0, ProductPicture.Height0 OR you can upload an image by passing a binary image in the ProductPicture.Image parameter in multipart/form-data format (similar to Twitter's update_profile_image API call).

Optional Fields:

  • ProductPicture.DisplayOrder This is the 0-indexed order of the product pictures relative to one another. If not provided, the picture will be last. If it is equal to the display order of another product picture for that product, the image will be inserted at that position, and the other images will have their display order incremented.

Sub-Resource: Users

GET /restapi/Product/{Id}/Users

Retrieve information on the users who are wishing for the given product Id.  

Notes:

  • This call is limited to 25 results. If you want to continue iterating, you can page through results by passing a Pg parameter - ex Pg=2. The default is one.
  • If you wish to limit the type of list the wishes are on, e.g. to only get the user's who have added a wish to a Pick List, use the ListType  parameter (List Type options are described in the List Resource).
  • Results are returned as a list of Users. Users with images will be returned first.

The ProductPicture Resource

GET /restapi/ProductPicture/Details/{ProductPictureId}

Use this call to look up a given product picture.

POST /restapi/ProductPicture/Edit/{ProductPictureId}

Use this call to edit a Product Picture after it was created.

POST /restapi/ProductPicture/Delete/{ProductPictureId}

Use this call to delete a product picture

The ShippingPolicy Resource

A shipping policy has a many-to-one relationship with a Product.  A Product can have a different shipping policy for each region.

>> Example Output << 

GET /restapi/ShippingPolicy/Details/{ShippingPolicyId}

Use this call to look up a given shipping policy

POST /restapi/ShippingPolicy/Edit/{ShippingPolicyId}

Use this call to edit a Shipping Policy after it was created

POST /restapi/ShippingPolicy/Delete/{ShippingPolicyId}

Use this call to delete a shipping policy

 

Notes:

  • Region is one of the following: Local, Domestic, Regional, Worldwide. Only one region policy is allowed per product. However, you can also leave the region empty.

The Purchase Resource

GET /restapi/Purchase/Details/{PurchaseId}

>> Example Output << 

Use this call to look up a given Purchase. If you are the buyer or seller associated with the purchase, transaction details will also be returned, such as the shipping address/

Notes:

  • Purchase.AccessType Supported values are "0" for Private, and "30" for Public (default). This indicates whether the buyer of the purchase is Public or Private (to the buyer and seller only).
  • Purchase.ViewerBuyerId Items sold by a user can always be associated with that user, but if Purchase.AccessType is set to Private, only the seller and buyer can view the id of the user who purchased the item, or view the item in a list of the buyer's purchased items.
  • Purchase.Status Supported values are "0" for Cancelled, "1" for Complete (default), and "2" for Pending.
  • Purchase.Price The unit price of the product at the time it was sold.
  • .

GET /restapi/User/{user_id}/Sold

Use this call to retrieve a list of items sold by the given user that have been purchased, along with product information.

>> Example Output<< 

GET /restapi/User/{user_id}/Purchased

Use this call to retrieve a list of items purchased by the given user, that you have permission to view.

Notes (for both `Sold` and `Purchased`):

  • If the logged in user is the seller or buyer, all purchases will be returned regardless of status. Otherwise only Complete purchases will be returned.
  • Optional Argument: Use Purchase.Status to filter the results by status if you are logged in as the buyer or seller.
  • The output contains the Product and Picture associated with each Purchase.

POST /restapi/Purchase/Share/{PurchaseId}

See details above for Wish.Share

The UserMessage Resource

This is how you send a message to another user.

>> Example Output << 

GET /restapi/UserMessage/Details/{MessageId}

View the details of a given message.

POST /restapi/UserMessage/Create/

Make this call to send a message from the logged in user to another user. Returns a serialized UserMessage as shown above.

Notes:

  • Required Parameters: UserMessage.RecipientUserId You must specify a recipient of the message. The API currently only supports one to one messaging.
  • Optional Parameters: UserMessage.Subject, UserMessage.Body, UserMessage.ProductId if you wish to associate the message with an existing product.
  • A successful call to this API will result in a UserMailbox entry being created in the logged-in user's Sent folder, as well as a UserMailbox entry in the recipient's Messages folder, both of which point to the same message.
  • A serialized UserMessage will be returned.

The UserMailbox Resource

This is an instance of a message in a user's mailbox.

GET /restapi/UserMailbox/Details/{MessageId}

View details of the message and its properties in the currently logged in user's mailbox.

>> Example Output << 

Notes:

  • UserMailbox.FolderType will be one of the following: 1 (Messages), 2 (SentItems), 3 (FriendRequests), 4 (ProductRecommendations), 5 (Comments), 6 (MobileQueries), 7 (DeletedItems). However, messages are only created in FolderType 1 (Messages) and 2 (SentItems), and there are no plans to support anything other than viewing the other types.
  • UserMailbox.Status is one of the following: 0 (New), 1 (Read), 2 (Accepted), 3 (Declined). The only applicable stati for messages created via the API are 0 (New) and 1 (Read), since Friend Requests can not be created through the APU at this time.

GET /restapi/UserMailbox/Index/

Retrieves all mailbox items for the logged-in user, ordered from newest to oldest.

POST /restapi/UserMailbox/Search

Allows you to paginate through the items in the user's mailbox, and filter them by criteria. Also returned in order from newest to oldest.

Optional Parameters:

  • ProductId - Retrieve all messages pertaining to the given productId.
  • UserId - Retrieve only those messages exchanged between the logged in user and the given userId.
  • FolderType - If not specified, all messages except for those in the deleted folder will be returned. Most useful for filtering for only sent (FolderType = 2) or received (FolderType = 1) messages.
  • Limit and Page - Must be used in conjunction, or otherwise all results will be returned. There are no default values, but the max value of Limit is 100, and Page is 0 indexed.

POST /restapi/UserMailbox/Edit/{MessageId}

Edit properties of the mailbox item for the given message.

The OAuthCredential Resource

This is how you specify a user's OAuth credentials in other systems.  Ex. if they use facebook connect, this is how you'd persist their access token.  All of the operations can only be performed on the currently authenticated user, which is why no UserId is required in any of the urls.

>> Example Output << 

GET /restapi/User/OAuthCredential/Details/{OAuthCredentialId}

Lists an individual OAuthCredential

POST /restapi/User/OAuthCredential/Create

Create an OAuthCredential for the current user.

POST /restapi/User/OAuthCredential/Edit/{OAuthCredentialId}

Edit the specified OAuthCredential. Note, you could also use the /Create method to edit a credential, if you'd prefer not to store the Id.

Notes:

  • OAuthCredential.SocialNetwork can be one of the following values: Facebook, Twitter, Shopify, Google.

The PaypalCredential Resource

This is how you specify a user's paypal account.

>> Example Output << 

GET /restapi/User/PaypalCredential/Details/{PaypalCredentialId}

Lists an individual UserPaypalCredential

POST /restapi/User/PaypalCredential/Create

Stores a Paypal account for the current user. Required Argument: PaypalCredential.Email

POST /restapi/User/PaypalCredential/Edit/{PaypalCredentialId}

Edit the specified PaypalCredential. Note, you could also use the PaypalCredential/Create method to edit a credential, if you'd prefer not to store the Id.

Notes:

  • We currently only store one Paypal account per User.

The Follow Resource

This is how you specify who a user would like to follow, and view who users are following and followed by.

GET /restapi/User/{user_id}/Following

Lists who a given user follows. If you omit the user_id, a list of who the logged in user is following will be provided.

>> Example Output << 

GET /restapi/User/{user_id}/Followers

Lists who is following the given user.

POST /restapi/User/Follow/Create/{user_id}

Indicate that the logged-in user would like to follow the given user.

POST /restapi/User/Follow/Delete/{user_id}

The logged in user no longer will follow the given user.

The MerchantClick Resource

Whenever someone clicks on a Wish or Product on Wishpot, or whenever a click is sent through the RedirectUrls that this API provides on Products and Wishes, clicks are recorded. Vendors can see clicks on their products, and Partners can see clicks that their users have made.

<MerchantClick xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.wishpot.com/restapi">
  <Id>55982</Id>
  <ProductId>402426</ProductId>
  <ProductVendorId>14485</ProductVendorId>
  <WishId xsi:nil="true"/>
  <UserId xsi:nil="true"/>
  <CurrentUserId>19338</CurrentUserId>
  <PartnerId>1</PartnerId>
  <AppType>2</AppType>
  <Url>http://www.etsy.com/view_listing.php?listing_id=48848446</Url>
  <CreatedTime>2011-07-06T22:36:30.377</CreatedTime>
</MerchantClick>  

GET /restapi/MerchantClick/Details/{click_id}

Details on an individual click. Probably not particularly useful aside from troubleshooting.

GET or POST /restapi/MerchantClick/Search

Search for clicks. This call uses the common Pg and Limit params for iterating through large collections of clicks. At least one of the following filers is required:

  1. MerchantClick.ProductVendorId - This is used to show only clicks on a given vendor's products.
  2. MerchantClick.PartnerChannel - When you send traffic through the RedirectUrl properties of Wishes and Products, you can append the parameter pchannel to those urls to track those clicks in any manner you please. You can then use this filter to get all clicks from that channel.

The following filters are optional:

  1. MinDate and MaxDate can be passed in YYYY-MM-DD format to filter on dates (inclusive)

The PriceDrop Resource

When Wishpot detects a price drop, according to a Vendor's configuration, we log that event. This is a simple, read-only way of accessing Price Drops. It does not require authentication.

GET /restapi/PriceDrop/

With no arguments, returns the last 250 price drops the system has encountered, across all categories.

The following filters are optional:

  1. ch - Channel. If a vendor has put themselves in a channel, you can see them when filtering by shopping channel. Supported channels are: WeddingRegistry, BabyRegistry, Fashion, Handmade. Keep in mind, these are the channels for the vendors, not the products. So, a vendor may have a price drop on a product that does not squarely fit into these categories.

The UserDevice Resource

This is how you associate a given device (e.g. an iPhone or an iPad) with a user, most notably so that device may receive push notifications of events on that device. A user may also specify by device which notifications they would like to receive.

GET /restapi/UserDevice/Details/{DeviceId}

>> Example Output << 

Use this call to look up a given UserDevice (that belongs to the logged-in User) with the given DeviceId (provided by the device itself).

GET /restapi/UserDevice/Index

Returns a list of all devices registered to the logged-in user.

POST /restapi/UserDevice/Create

Create an UserDevice for the current user. If there is an existing UserDevice for the logged in User with the same DeviceId, this will instead Edit the existing UserDevice.

Required Arguments:

  • UserDevice.DeviceId The unique id of the given device on its notification network. E.g. UUID on a device on the Apple network.
  • UserDevice.PushToken Secure token used to communicate with applicable network for push notifications.
  • UserDevice.Model Model of the device, E.g. "iPhone 3GS"

Optional Arguments:

  • UserDevice.Name Friendly name of the device - e.g. "Erica's iPhone"
  • UserDevice.Version
  • UserDevice.NotificationSetting.* - Boolean values to enable push notifications for the given event to that device. If none are provided at time of creation, they will be all set to false. Currently supported events are
    • Purchases (when someone purchases one of your items)
    • Followers (when someone starts to follow you),
    • NewMessages (the user has received a new message)
    • ProductPicks (another user has added a wish to their PickList for a product you are selling.)

POST /restapi/UserDevice/Delete/{DeviceId}

Delete the given device belonging to the logged in user. Should only be called if the user explicitly wishes to remove all information for a device, such as if they uninstall. If you wish to turn off Notifications, this should be done by calling /UserDevice/Edit/ .

GET /restapi/UserDevice/Edit/{DeviceId}

Edits the given device belonging to the logged in user.

Reports

We support various reports that allow partners to retrieve information about their users' activity.

GET or POST /restapi/Report/{ReportName}/?MinDate={MinDate}&MaxDate={MaxDate}

Supported Reports:

  1. ListsCreated Returns a report of all lists created in the given timeframe
  2. UserCreation Returns a report of all users who have signed up via your partner account in the given timeframe
  3. WishCreation Returns a report of all wishes created via your partner account's associated users
  4. ReservationSummary Returns a report of wishes purchased in the given timeframe
  5. MerchantClickByPartnerChannel If you create vendors, this is how you can retrieve a report on clicks those vendors' products have received, grouped by Partner Channel.

Search Results

When searching for things, the search results are wrapped in a common format, and then the Resources being searched are embedded in the response.

>> Example Output << 

Searches have a few common parameters:

  1. SearchTerm - The keyword you're looking for
  2. Pg - Which page you want, defaults to 1.
  3. Limit - The number of results you'd like to return on a given page. In most cases, this can't be higher than 100.

The format has a few sections:

  1. <FullResultCount> - the total number of matching results (even though this response may only show a page of them)
  2. <SearchTerm> and <CorrectedSearchTerm> - the search term you sent, as well as the search term that we spell-check corrected it to (currently this isn't happening, but will in the future).
  3. <BreadCrumbs> - If you have multiple search filters applied, will render a series of Segments (Described below) that could be used to represent a hierarchy.
  4. <Refinements> which contains multiple <Refinement> elements. Refinements summarize the statistics at different levels (price, category, etc). A Refinement is made up of multiple Segments.
  5. <Segment> is a part of a Refinement (or BreadCrumb). A Segment might be a price range, a category, etc. We give you a count of the matching elements at each segment. In addition, a link is provided that represents the url that a user could navigate to to see that segment applied online. The Id of the segment is the value that's passed in the url or filter.
  <Segment Id="131">
    <Name>Mac Laptops</Name>
    <Count>27</Count>
    <SiteUrl>http://www.wishpot.com/public/search.aspx?sk=book&prvid=4&st=limit%3D100%26oos%3DFalse%26cat%3D131</SiteUrl>
  </Segment>

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:

<Error>
  <Code>3248</Code>
  <Message>Human readable message here.</Message>
</Error>

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.
103100 Invalid Signature - if you're on the test server, the debug information will provide you with the normalized parameters that the server used to generate the signature. You can verify your signing algorithm with this online tool

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.

Feedback

If you have any questions, comments, or suggestions please e-mail developers@wishpot.com or post in our developer forum. We will be adding more API calls in the future and will be happy to work on new calls to meet your specific needs.