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 API provides a way to get those owner notes for a time interval. 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/ssapi/purchases?partner_id=<partner_id>&from_date=<from_date>&to_date=<to_date>


GET Request Parameters


Parameter

Value

Description

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.

from_date

String

The format for the date-time string is: %Y-%m-%dT%H:%M:%SZ

%Y= Year with century as a decimal number[2013,2012].

%m=Month as a decimal number [01-12].

%d= Day of the month as a decimal number [01,31].

%H= Hour (24-hour clock) as a decimal number [00,23].

%M= Minute as a decimal number [00,59]. %S= Second as a decimal number [00,60].

to_date

String

The format for the date-time string is: %Y-%m-%dT%H:%M:%SZ

%Y= Year with century as a decimal number[2013,2012].

%m=Month as a decimal number [01-12].

%d= Day of the month as a decimal number [01,31].

%H= Hour (24-hour clock) as a decimal number [00,23].

%M= Minute as a decimal number [00,59]. %S= Second as a decimal number [00,60].



Response Fields for JSON response



Field

Description

Original Value / Type

status_code

Status of the response

1: Success

2: Error

entity_count

Number of entities or owner notes in the given time period. This is the number of owner notes which are present in the entities list in the response

integer

entity_id

Internal unused field (deprecated*)

null

entity_type

Type of the entities requested. For owner notes of the shared purchases the value is always 1 (deprecated*)

1

entities [

{

JSON Array of

fb_uid

Facebook user id provided by facebook

Long integer

first_name

First name of the user who shared the story

String

last_name

Last name of the user who shared the story

String

id

Internal unused field

Alphanumeric String

product_id

Product id of the product which user shared.

Alphanumeric String

entity_type

Type of the entity. The value is always 1 in case of purchase stories (deprecated*)

1

merchant_key

Used to identify merchants in ShopSocially

String

image

Link url of the product shared

String

formatted_creation_time

The Formated UTC time at which the product story was created

Long UTC

creation_time

The UTC time at which the product story was created

Long UTC

owner_note

The story that user has written while sharing the product

String

image_width

Width of the product image

Integer

image_height

Height of the product image

Integer

currency_type

Currency of the product purchased

String

attached_link

Link url of the product which is shared and whose owner note is present

String

title

Title of the product shared

String

price

Price of the product shared

Float

classified

Internal unused field

Integer

merchant_name

Name of the merchant associated with ShopSocially

String

}

*deprecated fields may be removed in the higher versions of the api. It is recommended not to use those fields.


Example:

· http://api.shopsocially.com/ssapi/purchases?partner_id=10015&from_date=2013-03-01T00:00:00Z&to_date=2013-03-02T00:00:00Z


Note: The date-time fields from_date and to_date expects the time to be in UTC timezone and in ISO format. Please note ‘T’ delimiter between date and time, and ‘Z’ at the end of these fields.


The following JSON object is returned:


{

"status_code": 1,

"entity_type": 1,

"entity_count": 154,

"entities": [

{

"fb_uid": "100000003204023",

"first_name": "Martha",

"last_name": "Staff",

"product_id": "650691573",

"entity_type": 1,

"merchant_key": "cafepress",

"image": "http://i1.cpcache.com/product/650691573.jpg?side=F&color=White&height=350&width=350",

"formatted_creation_time": "Mar 01, 2013",

"creation_time": "2013-03-01 00:02:40.538000",

"image_width": 350,

"id": "512ff0204245234c65000092",

"currency_type": "USD",

"image_height": 350,

"attached_link": "http://www.cafepress.com/+long_sleeve_tshirt,650691573",

"owner_note": "got myself an \"OM\" shirt with cat...to express my love for yoga and cats!",

"classified": 0,

"title": "Long Sleeve T-Shirt",

"price": 32.990000000000002,

"merchant_name": "CafePress"

},

{

"fb_uid": "1565595408",

"first_name": "Keith",

"last_name": "Gault",

"product_id": "348260468",

"entity_type": 1,

"merchant_key": "cafepress",

"image": "http://i1.cpcache.com/product/348260468.jpg?side=F&color=Black&height=350&width=350",

"formatted_creation_time": "Mar 01, 2013",

"creation_time": "2013-03-01 00:03:11.348000",

"image_width": 0,

"id": "512ff03f2bba01728400008e",

"currency_type": "USD",

"image_height": 0,

"attached_link": "http://www.cafepress.com/+dark_tshirt,348260468",

"owner_note": "Rachel. Enjoy ;-)",

"classified": 0,

"title": "Dark T-Shirt",

"price": 22.989999999999998,

"merchant_name": "CafePress"

}...

]

}



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.

{"status_code": 2, "entities": [], "error": "failure: time data '20-03-01T00:00:00Z' does not match format '%Y-%m-%dT%H:%M:%SZ'", "entity_count": 0}

“error” field in the JSON response shows what kind of error has occurred.