Description


When shoppers share their purchase with friends using ShopSocially’s Share-a-Purchase app, a user-generated product story is created in the form of user “comments”. Such product stories can be used as “reviews” or “social proof” on product pages on the merchant site. This document explains how to access the product stories related to a certain product. The API is provided as a REST service as follows.


URL Construction


  • HTTP Method: HTTP Get
  • Start URL: http://api.shopsocially.com
  • Version Number: v1.0

Full Request URL


http://api.shopsocially.com/v1/products/{product_id}/stories?partner_id=<partner_id>&count=<story_count>

OR

http://api.shopsocially.com/v1/products/{product_url}/stories? partner_id=<partner_id>&count=<story_count>



GET Request Parameters


Parameter

Value

Description

{product_id} or {encoded_product_url_string}

(token)

Alpha-numeric string (either the product_id or a double encoded product url string is required.)

If the “product_id” is provided by merchant in the advanced integration for the Share-a-Purchase app, this “product_id” should be used as the token.  

If product id is not provided, the “encoded_product_url_string”, which is used in the Share-a-Purchase app can be used as the token to retrieve the comments. Please note that usage of the product url requires double URL encoding of the url string before being used as the token. Please see example usage for more detail.

partner_id

32 character alpha-numeric string (required)

Partner ID is a unique ID assigned to each merchant that creates an account with ShopSocially. The unique ID is a 32 character alpha-numeric string.

Count

Integer (optional)

Count of the number of product stories returned in a single request. If no count value is provided, the default value is 10.

 


Response Fields for JSON response


Field

Description

Original Value / Type

info

An encapsulating JSON object. Contains

title

The product title passed by the merchant in the Share-a-Purchase app.

String

url

The product url passed by the merchant in the Share-a-Purchase app.

String

image

The product image url passed by the merchant in the Share-a-Purchase app.

String

image_width

Width of the product image in pixels

Integer

image_height

Height of the product image in pixels

Integer

id

The product id

String

comments [

{

JSON Array of

first_name

First name of the user who shared the product story

String

last_name

Last name of the user who shared the product story

String

creation_time

The UTC time at which the product story was created

Long UTC

user_picture

Link to a square 50 x 50 px image of the user who shared the product story

String

message

The comment written by the user as a part of the shared product story

String

id

ID of the product story object

Alpha-numeric string

} ]

next

If more product stories are present than the count requested in the present query, this is the next url at which you can request to get more comments

URL string



Example Usage


Usage with the {product_id} token When the URL is invoked with {product_id}


http://api.shopsocially.com/v1.0/products/346676/stories?partner_id= ddfd2404ace5c5c20846c42f3ac443a4&count=2


The following JSON object is returned:


{"info":  

{"title": "Bill Maher But I'm Not Wrong Mug",  

"url": "http://store.hbo.com/detail.php?p=346676",  

"image": "https://securestore.hbo.com//img/product/catl/00346676-115423.jpg",  

"image_width": 687,  

"image_height": 687,  

"id": "346676"},  

"comments": [

{

"first_name": "Kay",  

"last_name": "Duehrssen",  

"creation_time": "2012-11-19 00:21:12.074000",  

"user_picture":  

"https://graph.facebook.com/100003283723387/picture?type=square",  

"message": "Special birthday gift for a real fan",  

"id": "50a97b7842452331d7000374"

},  

{

"first_name": "Admira",  

"last_name": "Kulalich",  

"creation_time": "2012-11-08 07:18:09.225000",  

"user_picture":  

"https://graph.facebook.com/1554060907/picture?type=square",  

"message": "My husband is Bday coming,and i purchase him a Mug from his  

favorite comedian an guy on TV..He will love it...Happy Bday my love:)))))  

and many,many more... Your family loves u and your son is growing to be  

very much so like you,wich is great dad, husband,son and artist...",  

"id": "509b5cb1424523644c0000a3"},

],  

"next": "http://shopsocially.com/ssapi/products/346676/comments?start_index=2&count=10"

}


Usage with the {encoded_product_url_string} token


This usage is applicable if the product_id is not passed to the REST API call.


Double encode the product URL before passing it to the REST API call


Example:


Suppose the product URL is

http://www.bestbullysticks.com/home/bbs/page_7098/12_inch_thick_odor_free_bully_sticks.html


You must double encode the product URL before passing it to the API. For example in javascript, you can double encode the URL by using the call.

encoded_product_url_string = encodeURIComponent(encodeURIComponent(product_url));


In case of the above product URL, the call to double encode the product URL will look like:

encoded_product_url_string = encodeURIComponent(encodeURIComponent('http://www.bestbullysticks.com/home/bbs/page_7098/12_inch_thick_odor_free_bully_sticks.html'));


This generates an encoded_product_url_string as follows:

http%253A%252F%252Fwww.bestbullysticks.com%252Fhome%252Fbbs%252Fpage_7098%252F12_inch_thick_odor_free_bully_sticks.html  


You can now pass the encoded_product_url_string to the API as follows:

http://api.shopsocially.com/v1.0/products/http%253A%252F%252Fwww.bestbullysticks.com%252Fhome%252Fbbs%252Fpage_7098%252F12_inch_thick_odor_free_bully_sticks.html/stories?partner_id= ddfd2404ace5c5c20846c42f3ac443a4&count=2


The JSON object returned is identical to the response when invoking REST API with the {product_id} token.


Limits


There are no rate limits currently. Customers will be informed with sufficient lead time before rate limits are imposed. 

 


Error Responses


In case of errors, a JSON object is returned with the following semantics.


{"error": "100: Product Not Found"}

Error Code

Description

200

The merchant name was not passed to in the partner_id field or it is incorrect

100

The selected product was not found for the merchant’s partner_id.


Additional responses may be added in the future.