The Loyalty Program API allows you to extend the loyalty program beyond your website, and have a common rewards program for all your sales channels. It also enables you to customize the implementation of the program on your website.

 

This document gives the API specifications of the Loyalty Program along with examples of each function.


URL Construction


The ShopSocially API exports sensitive data, so any call to the ShopSocially API needs to be authenticated. For authenticating an API call, you have to send your Partner ID, and a API Key in the HTTP header of each API request. 

To access Partner ID, and the API Key, please follow the steps given below:

1. Login to your Merchant Center Console.
2. Navigate to Basic Settings > General Information, to find your Partner ID, and API Key. Refer to Figure: Partner ID And API Key.

Figure: Partner ID And API Key


Please note: If you don't see the API Key on your dashboard, please write to support@shopsocially.com

3. Send the keys in the HTTP header of each API request as given below:
'api-key' : '<your-api-key>'
'partner-id' : '<your-partner-id>'
If you do not send the correct keys in the HTTP header for an API request, you will receive a 401 Unauthorized response. For more information about response codes, visit Response Codes guide.

API functions


The below table shows all the available API functions. Click on required API function name for full specification.

Sr. No. Name Description
1 Award Points
Award points to a user for any activity.
2 Redeem Points
Deduct points from a user’s account in return for a coupon code.
3 Deduct Points
Deduct points from a user’s account for any other reason, not necessarily related
to redemption.
4 Get All Transactions
Get a list of all transactions within the loyalty program for a date range.
5 Get Transaction
Get the details of a particular transaction using the transaction ID.
6 Update transaction
Update the details of a particular transaction using the transaction ID.
7 Get all users
Get list of all users enrolled in loyalty program.
8 Get User
Get the user information for a particular user using the email ID.
9 Create user
Create a loyalty user.
10 Update user
Update a existing loyalty user.
11 Get user Transactions
Get the transaction information for a user using the email ID.
12 Get all activities
Get a list of loyalty activities which can earn loyalty points.
13 Create Activity
Create a new loyalty activity.
14 Get Activity
Get information about a particular activity using the Activity ID.
15 Update Activity
Update an activity using the Activity ID.
16 Get All Redemptions
Get a list of redemption options in the loyalty program.
17 Create Redemption
Create a new redemption option.
18 Get Redemption
Get details about a redemption option using the Redemption Option ID.
19 Update Redemption
Update a redemption option using the Redemption Option ID.
20 Get all Loyalty Levels
Get a list of all levels.
21 Create Loyalty Level
Create a new loyalty level.
22 Update Loyalty Level
Update a loyalty level using a certain loyalty ID.
23 Get Loyalty Level
Get information about a certain loyalty level.
24 Return Order
Can be used to deduct points of a User when the user returns an order. 
25 Summary
 

1. Award Points

 
This can be used to award points to a user for any activity. Points will be awarded based on the user's email ID.
 
Type of Request: POST
Endpoint: /loyalty/award

Table 1: Post Award Points Request Parameters
Parameter Value Is Required Description
user_email String Value Required The email of the user to whom points have to be awarded.
points_passed Number
Optional(if activity type is fixed)

Required(if activity type is bonus multiplier) 


If the activity is configured to award fixed number of points, the points passed will override the value set in the configuration. 
If the activity is configured to use a multiplier to award points, this becomes a mandatory parameter as the points cannot be awarded without the base value.
activity_id String Value Required The activity for which points needs to be awarded. The activity ID is available in the merchant center in the activity configuration.
 order_id  String Value Optional  When points are being awarded for purchase activity, it is recommended to pass order ID of the purchase transaction .This ensures that points for a particular transaction are awarded only once. 


1.1 Response Fields for JSON response

{
"data":{
            "user_id":<SS User ID>,
            "user_email":<User Email>,
            "user_last_name":<User Last Name>,
            "user_first_name":<User First Name>,
            "activity_id":<Activity ID>,
            "activity_name":<Activity Name>,
            "id":<Transaction ID>,
            "transaction_type":"award",
            "points":<Points Awarded>,
            "points_status":<Points Status(auto_approved, approved,pending,auto_rejected, 
            rejected,deducted)>,
            "partner_id":<Partner ID>,
            "created_time":<Award Created Time>
            },
"success":true
}

1.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics.
 
{
  "reason":"Invalid Activity ID",
  "success":false
}

Example:

Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.

An example curl request will look like this:

curl–X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data "user_email= <User’s email ID>" --data " points_passed = <number of points to be awarded>" --data " activity_id= <activity Id>https://api.shopsocially.com/v2/loyalty/award

You can replace your partner ID, API key, User email ID, points passed and activity ID in the above request and run it from the command line to see the response. An example response will look like the one below:

{
"data":{
            "user_id":6176be2d5e,
            "user_email": Rohit@shopsocially.com,
            "user_last_name": B,
            "user_first_name":Rohit,
            "activity_id":made_a_purchase,
            "activity_name": Made a Purchase,
            "id":54aeb7b4f283c6176be2d5ed,
            "transaction_type":"award",
            "points": 100,
            "points_status":auto_approved,
            "partner_id":69c62d683db96c7cabf8db0109be6bb1,
            "created_time":30-Mar-15 19:20:22
            },
"success":true
}


2. Redeem Points

This is used to redeem points for a user. Based on the redemption option chosen, points will be deducted from the user's account and a coupon code will be returned in the response.

Type of Request: POST

Endpoint: /loyalty/redeem

Full URL: https://api.shopsocially.com/v2/loyalty/redeem


Table 2: Post Redeem Points Request Parameters

Parameter Value Is Required Description
user_email String Value Required The email of the user who wishes to redeem the points.
redemption_id String Value Required The ID of the desired redemption option. The redemption ID is available in the merchant center.

2.1 Response Fields for JSON response

{
"data":{
            "user_id":<SS User ID>,
            "user_email":<User Email>,
            "user_last_name":<User Last Name>,
            "user_first_name":<User First Name>,
            "redemption_id":<Redemption ID>,
            "redemption_name":<Redemption Name>,
            "redemption_value":<Redemption Value>,
            "id":<Transaction ID>,
            "transaction_type":"redeem",
            "points":<Points Redeemed>,
            "points_status":"redeemed",
            "coupon_code":<Coupon Code>,
            "partner_id":<Partner ID>,
            "created_time":<Created Time>
            },
"success":true
}

2.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics.:
 
{
  "reason":"Invalid Redemption ID",
  "success":false
}

Example:

Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
A curl example request will look like this:
curl–X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " user_email = <User’s email ID>" --data " redemption_id= <redemption ID>"https://api.shopsocially.com/v2/loyalty/redeem
You can replace your partner ID, API key, User email ID and Redemption ID in the above request and run it from the command line to see the response. An example response will look like the one below:
{
"data":{
            "user_id":6176be2d5e,
            "user_email": Rohit@shopsocially.com,
            "user_last_name": B,
            "user_first_name":Rohit,
            "redemption_id":$50_gift_card,
            "redemption_name":$50 Gift Card,
            "redemption_value": $50,
            "id":54aeb7b4f283c6176be2d5ed,
            "transaction_type":"redeem",
            "points": 1000,
            "points_status":"redeemed",
            "coupon_code": GET50OFF,
            "partner_id":9c62d683db96c7cabf8db0109be6bb,
            "created_time":30-Mar-15 19:20:22   
},
"success":true
}


3. Deduct Points

This is used to deduct points from a user’s available points. This deduction may not be related to redemption.
 
Type of Request: POST
Endpoint: /loyalty/deduct

Table 3: Post Deduct Points Request Parameters
Parameter Value Is Required Description
user_email String Value Required The email of the user who wishes to redeem the points.
reason String Value Required The reason for deduction.
points_passed String Value Required The number of points to be deducted.

3.1 Response Fields for JSON response

{
"data":{
            "user_id":<SS User ID>,
            "user_email":<User Email>,
            "user_last_name":<User Last Name>,
            "user_first_name":<User First Name>,
            "id":<Transaction ID>,
            "transaction_type":"deduct",
            "points":<Points Deducted>,
            "points_status":"deducted",
            "available_points":<Available Points>,
            "partner_id":<Partner ID>,
            "created_time":<Created Time>
            },
"success":true
}

3.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics:
 
{
 "reason":"Invalid User",
 "success":false

Example:

Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
A curl example request will look like this -
curl–X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " user_email = <User’s email ID>" --data " reason = <reason>" --data "points_passed: <points_passed>" https://api.shopsocially.com/v2/loyalty/deduct

You can replace your partner ID, API key, User email ID, reason and points passed in the above request and run it from the command line to see the response. An example response will look like the one below:

{
"data":{
            "user_id":6176be2d5e,
            "user_email": Rohit@shopsocially.com,
            "user_last_name": B,
            "user_first_name":Rohit,
            "id":54aeb7b4f283c6176be2d5ed,
            "transaction_type":"deduct",
            "points": 1000,
            "points_status":"deducted",
             "available_points":1500,
            "partner_id":9c62d683db96c7cabf8db0109be6bb,
            "created_time":Monday, 30-Mar-15 19:20:22 UTC
            },
"success":true
}


4. Get All Transactions
 
Gets list of all transactions in the given period
 
Type of Request: GET
Endpoint: /loyalty/transactions

Table 4: Get All Transactions Request Parameters

Parameter Value Is Required Description
from_date String Value (MM/DD/YYYY) Required The start date.
to_date String Value (MM/DD/YYYY) Required The end date.
points_status List of Strings (['pending','auto_approved','approved',
'auto_rejected','rejected', 'exhausted', 'expired'])
Optional The status of the transactioni.e pending, auto_approved, approved, auto_rejected, rejected.

Note:
Exhausted are awarded points which are redeemed by user.
 
Expired points are awarded points which user has not redeemed within validity period.
start_index Number (Defaults to zero) Optional The index from where data needs to be fetched.

4.1 Response Fields for JSON response


{

"data": {

             "total": 9,

             "next_start_index": 10,

             "transactions": [

             {

             "points_status": "approved",

             "points_used": 0,

             "available_points": 22,

             "points_expired": 0,

             "created_time": "14-Jan-2016 06:33:22",

             "updated_time": "14-Jan-2016 06:33:22",

             "id": "569741320daac146edac90c0",

             "user_id": "54b3b13e0daac1321e07ce1f",

             "points_expiration_date": "14-Mar-2016 06:33:22",

             "approved_by": null,

             "qualified_points": true,

             "redemption_value": null,

             "activity_id": "shared_photo_via_desktop_or_mobile",

             "user_first_name": "Ezio",

             "order_id": "1452749387649368175",

             "reason": null,

             "points_deducted": 0,

             "merchant_id": "137692186f3cfaf9fc0839d8da0934f6",

             "redemptions_list": null,

             "approved_time": "14-Jan-2016 06:33:22",

             "redemption_name": null,

             "auto_approval_date": "",

             "transaction_type": "award",

             "user_last_name": "Auditore",

             "coupon_code": null,

             "points": 22,

             "redemption_id": null,

             "activity_name": "Shared Photo via Mobile or Desktop",

             "user_email": "subhrajyoti@shopsocially.com"

             },

             {

             "points_status": "approved",

             "points_used": 0,

             "available_points": 55,

             "points_expired": 0,

             "created_time": "14-Jan-2016 06:33:13",

             "updated_time": "14-Jan-2016 06:33:13",

             "id": "569741290daac146edac90bf",

             "user_id": "54b3b13e0daac1321e07ce1f",

             "points_expiration_date": "14-Mar-2016 06:33:13",

             "approved_by": null,

             "qualified_points": true,

             "redemption_value": null,

             "activity_id": "shared_photo_via_desktop_or_mobile",

             "user_first_name": "Ezio",

             "order_id": "1452749387649368175",

             "reason": null,

             "points_deducted": 0,

             "merchant_id": "137692186f3cfaf9fc0839d8da0934f6",

             "redemptions_list": null,

             "approved_time": "14-Jan-2016 06:33:13",

             "redemption_name": null,

             "auto_approval_date": "",

             "transaction_type": "award",

             "user_last_name": "Auditore",

             "coupon_code": null,

             "points": 55,

             "redemption_id": null,

             "activity_name": "Shared Photo via Mobile or Desktop",

             "user_email": "subhrajyoti@shopsocially.com"

             }

             ],

             "more": false

             },

"success": true

}



4.2 Error Responses

 

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

 

{

 "reason":"missing parameters",

 "success":false

}

 

Example:


https://api.shopsocially.com/v2/loyalty/transactions?from_date=03/01/2015&to_date=03/31/2015&points_status=["approved","auto_approved"]

 

When such a request is made, a JSON object like the one below will be returned. The response will return only 10 records for each request. You will have to make iterative requests till the “more” parameter returns ‘False’.


{

"data":{

            "total": 250

            "next_start_index":100,

            "transactions":[

            {

            "activity_id":"Made_a_Purchase",

            "activity_name":"Made a Purchase",

            "user_id":"6176be2d5e",

            "user_first_name":"Rohit",

            "user_last_name":"B",

            "user_email":"Rohit@shopsocially.com",

            "redemption_id":null,

            "redemption_name":null,

            "id":"550ff099fa0eaa0767086968",

            "approved_time":"20-Mar-15 19:20:22",

            "auto_approval_date":null,

            "points_status":"approved",

            "transaction_type":"award",

            "coupon_code":null,

            "points": 100,

            "approved_by":"Jai",

            "created_time":"20-Mar-15 19:20:22",

            "updated_time":"30-Mar-15 19:20:22",

            "merchant_id":"3994293d288f628bb94adde076ab36b5",

            },….{}

            ],

            "more":true< This will be true when there are more records to be fetched>

            },

"success":true

}



5. Get Transaction 

 

Gets detail of a particular transaction

 

Type of Request: GET

Endpoint: /loyalty/transactions/{transaction_id}

Full URL: https://api.shopsocially.com/v2/loyalty/transactions/{transaction_id}

 


Get Request Parameters: No Request parameters for this function.


5.1 Response Fields for JSON response

 

{

"data":{

            "activity_id":<Activity ID>,

            "activity_name":<Activity Name(null in case of Redeem)>,

            "user_id":<SS User ID>,

            "user_first_name":<User First Name>,

            "user_last_name":<User Last Name>,

            "user_email":<User Email>,

            "redemption_id":<Redemption Id(null in case of Award)>,

            "redemption_name":<Redemption Name(null in case of Award)>,

            "coupon_code":<Coupon Code(null in case of Award)>,

            "id":<Transaction ID>,

            "auto_approval_date":<Auto Approval Date(present only in case of transaction created in pending state)>,

            "points_status":<Points Status (pending,approved,auto_approved,rejected,auto_rejected,redeemed)>,

            "transaction_type":<Transaction Type(award/redeem)>,

            "points":<Points awarded/redeemed>,

            "approved_by":<Approved By(present in case of manually approved)>,

            "approved_time":<Approved Time(blank in case redeem)>,

            "created_time":<Created Time>,

            "updated_time":<Updated Time>,

            "partner_id":<Partner ID>,

            },

"success":true

}


5.2 Error Responses

 

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


{

 "reason":"Invalid Transaction ID",

 "success":false

}


Example:


This is an example of a curl request:


https://api.shopsocially.com/v2/loyalty/transactions/54aeb7b4f283c6176be2d5ed

 

When such a request is made, a JSON object like the one below will be returned:


{

"data":{

            "activity_id":"Made_a_Purchase",

            "activity_name":"Made a Purchase",

            "user_id":"6176be2d5e",

            "user_first_name":"Rohit",

            "user_last_name":"B",

            "user_email":"Rohit@shopsocially.com",

            "redemption_id":null,

            "redemption_name":null,

            "id":"550ff099fa0eaa0767086968",

            "approved_time":"20-Mar-15 19:20:22",

            "auto_approval_date":null,

            "points_status":"approved",

            "transaction_type":"award",

            "coupon_code":null,

            "points": 100,

            "approved_by":"Jai",

            "created_time":"20-Mar-15 19:20:22",

            "updated_time":"30-Mar-15 19:20:22",

            "merchant_id":"3994293d288f628bb94adde076ab36b5",

            },

"success":true

}



6. Update Transaction
 
Update a particular transaction using the transaction ID. The transaction ID can be fetched using the Get All Transactions call.
 
Type of Request: PUT
Endpoint: /loyalty/transactions/{transaction_id}

Table 5: Put Update Transaction Request Parameters
Parameter Value Description
points_status String Value The status of the point.

6.1 Response Fields for JSON response

{
"data":{
            "activity_id":<Activity ID>,
            "activity_name":<Activity Name(null in case of Redeem)>,
            "user_id":<SS User ID>,
            "user_first_name":<User First Name>,
            "user_last_name":<User Last Name>,
            "user_email":<User Email>,
            "redemption_id":<Redemption Id(null in case of Award)>,
            "redemption_name":<Redemption Name(null in case of Award)>,
            "coupon_code":<Coupon Code(null in case of Award)>,
            "id":<Transaction ID>,
            "auto_approval_date":<Auto Approval Date(present only in case of transaction created in pending state)>,
            "points_status":<Points Status (pending,approved,auto_approved,rejected,auto_rejected,redeemed)>,
            "transaction_type":<Transaction Type(award/redeem)>,
            "points":<Points awarded/redeemed>,
            "approved_by":<Approved By(present in case of manually approved)>,
            "approved_time":<Approved Time(blank in case redeem)>,
            "created_time":<Created Time>,
            "updated_time":<Updated Time>,
            "partner_id":<Partner ID>,
            },
"success":true
}

6.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics:
 
{
 "reason":"Invalid Transaction ID",
 "success":false

Example:

Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
An example curl request will look like this:
curl–X PUT--header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " points_status = <points_status>"https://api.shopsocially.com/v2/loyalty/transactions/550ff099fa0eaa0767086968

You can replace your partner ID and API key in the above request and run it from the command line to see the response. An example response will look like the one below:

{
"data":{
            "activity_id":"Made_a_Purchase",
            "activity_name":"Made a Purchase",
            "user_id":"6176be2d5e",
            "user_first_name":"Rohit",
            "user_last_name":"B",
            "user_email":"Rohit@shopsocially.com",
            "redemption_id":null,
            "redemption_name":null,
            "id":"550ff099fa0eaa0767086968",
            "approved_time":"20-Mar-15 19:20:22",
            "auto_approval_date":"",
            "points_status":"approved",
            "transaction_type":"award",
            "coupon_code":null,
            "points": 100,
            "approved_by":"Jai",
            "created_time":"20-Mar-15 19:20:22",
            "updated_time":"30-Mar-15 19:20:22",
            "merchant_id":"3994293d288f628bb94adde076ab36b5"
            },
"success":true
}


7. Get all users

This will get all the users enrolled in the loyalty program.

Type of Request: GET
Endpoint: /loyalty/users

Table 6: Get All Users Request Parameters
Parameter Value Is Required Description
from_date String Value (MM/DD/YYYY) Required The start date.
to_date String Value (MM/DD/YYYY) Required The end date.
filter_by Accepted values
enrollment_date' , 'last_activity_date
Optional The date field to apply the from_date and to_date range.
start_index Number (Defaults to zero) Optional The start index to fetch the data from. If not specified, the start index will be 0.
count Number (Defaults to 100) Optional Number of records to fetch. If not specified, the count will be 100.

7.1 Response Fields for JSON response

{
"data": {
             "next_start_index": 2,
             "total_loyalty_users": 4480,
             "loyalty_users": [
             {
             "loyalty_life_time_level_name": "",
             "loyalty_lifetime_level_id": "",
             "expiration_schedule": [],
             "last_name": "Flores",
             "redeemed_points": 0,
             "last_award_transaction": {},
             "gender": "unknown",
             "dashboard_url": "https://shopsocially.com/loyalty/predatornutrition/user/
             56d62cb9735f833785f95ef5/dashboard",
             "first_name": "Brandon",
             "profile_image_url": "https://d1qbqkkh49kht1.cloudfront.net/
             65d9acdb2b629f0520a12f4c126fbe48.png", 
             "available_points": 0,
             "loyalty_level_id": "",
             "loyalty_level_name": "",
             "user_id": "56d62cb9735f833785f95ef5",
             "user_email": "Brandon.wafc@hotmail.co.uk"
             },
             {
             "loyalty_life_time_level_name": "",
             "loyalty_lifetime_level_id": "",
             "expiration_schedule": [],
             "last_name": "Williams",
             "redeemed_points": 0,
             "last_award_transaction": {
             "date": "01-Mar-2016 23:51:58",
             "points": 340,
             "name": "Made a Purchase"
             },
             "gender": "unknown",
             "dashboard_url": "https://shopsocially.com/loyalty/predatornutrition/user
             /56d627733b433356eef79002/dashboard",
             "first_name": "Samuel",
             "profile_image_url": "https://d1qbqkkh49kht1.cloudfront.net
             /65d9acdb2b629f0520a12f4c126fbe48.png",
             "available_points": 1040,
             "loyalty_level_id": "leopard",
             "loyalty_level_name": "Leopard",
             "user_id": "56d627733b433356eef79002",
             "user_email": "sam@acosproductionservices.co.uk"
             }
             ],
             "more": true
             },
"success": true
}

7.2 Error Responses

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

{
  "reason":"MissingParams",
  "success":false
}

Example:

This is an example of a curl request:

 
When such a request is made, a JSON object like the one below will be returned: 
{
"data":{
            "users":[{
            "user_id":6176be2d5e,
            "user_email": Rohit@shopsocially.com,
            "first_name":Rohit,
            "last_name": B,
            “gender”:male,
            "profile_image_url": http://....,
            "redeemed_points": 1000,
            "available_points": 200,
            "loyalty_level":"platinum"
            "last_activity_date":"29-Oct-2015 13:03:45"
            },…{}],
            "more":true,
            "next_start_index":10,
            "total":200
            },
"success":true
}


8. Get User
 
This will get the details of the user along with available, and redeemed points .

Type of Request: GET
Endpoint: /loyalty/users/{user_email}
Full URL: https://api.shopsocially.com/v2/loyalty/users/{user_email}

Get Request Parameters: No Request parameters for this API.


8.1 Response Fields for JSON response


{

"data":{

            "user_id":<SS User ID>,

            "user_email":<User Email>,

            "first_name":<User First Name>,

            "last_name":<User Last Name>,

            “gender”:<Gender>,

            "profile_image_url":<Profile Image url>,

            "redeemed_points":<Redeemed Points>,

            "available_points":<Available Points>,

            "loyalty_level_id":"platinum",

            "loyalty_lifetime_level_id":"platinum_lifetime",

            "user_language":<User Language>,

            "user_status":<User Status>

            "expiration_schedule": [{"expiration_date": "07-Jan-2016 23:59:59","points": 34226}],

   "last_award_transaction": {"date": "07-Dec-2015 13:23:35","points": 300,"name": "Became a Twitter              Follower"}

            },

"success":true

}


8.2 Error Responses

 

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

 

{

 "reason":"Invalid User",

 "success":false

}


Example:


This is an example of a curl request:


https://api.shopsocially.com/v2/loyalty/users/rohit@shopsocially.com

 

When such a request is made, a JSON object like the one below will be returned:

 

{

"data":{

            "user_id":6176be2d5e,

            "user_email": Rohit@shopsocially.com,

            "first_name":Rohit,

            "last_name": B,

            "gender": "male",

            "profile_image_url": http://....,

            "redeemed_points": 1000,

            "available_points": 200,

            "loyalty_level":"platinum",

            "merchant_uid":""

            },

"success":true

}



9. Create User

This will get the details of the user along with available and redeemed points.

Type of Request: POST
Endpoint: /loyalty/users

Table 7: Post Create User Request Parameters
Parameter Value Is Required Description
first_name String Value Required First Name of the user.
last_name String Value Required Last Name of the user.
email String Value Required Email of the user.
uid String Value Required User ID of the user.
gender String Value (male/female) Optional Gender of the user.
profile_image_url String Value Optional Profile Image URL of the user.
loyalty_level_id String Value Optional The loyalty level in which user will be moved.

9.1 Response Fields for JSON response

{
"data":{
            "user_id":<SS User ID>,
            "user_email":<User Email>
            "first_name":<User First Name>,
            "last_name":<User Last Name>,
            "profile_image_url":<Profile Image url>,
            "gender":<User Gender>
            "redeemed_points":<Redeemed Points>,
            "available_points":<Available Points>,
            "loyalty_level_id":<Loyalty Level>,
            "loyalty_lifetime_level_id":<Loyalty Level Lifetime>,
            "merchant_uid":<User ID provided by the merchant>
            },
"success":true
}

9.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics.:
 
{
 "reason":"Invalid User",
 "success":false
}

Example:

This is an example of a curl request:

curl –X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data "user_email=<user-email>" --data "first_name=<first-name>" --data "last_name=<last-name>" –data "profile_image_url=<profile-image-url>" --data "loyalty_level=<loyalty-level> --data "uid=<uid>"https://api.shopsocially.com/v2/loyalty/users
 
When such a request is made, a JSON object like the one below will be returned:

{
"data":{
            "user_id":6176be2d5e,
            "user_email": Rohit@shopsocially.com,
            "first_name":Rohit,
            "last_name": B,
            "profile_image_url": http://....,
            "redeemed_points": 1000,
            "available_points": 200,
            "loyalty_level_id":"platinum",
            "loyalty_lifetime_level_id":"platinum_lifetime",
            "merchant_uid":"ajk12k34"
            },
"success":true
}


10. Update User


This function is only applicable to the users created through the merchant’s authentication function. The details of the user, for user ID passed by merchant, will be updated. The users created through the ShopSocially authentication cannot be updated.

Type of Request: PUT
Endpoint: /loyalty/users/{uid}


Table 8: Put Update User Request Parameters
Parameter Value Description
loyalty_level_id String Value The loyalty level in which user will be moved.

10.1 Response Fields for JSON response


{

"data":{

            "user_id":<SS User ID>,

            "user_email":<User Email>

            "first_name":<User First Name>,

            "last_name":<User Last Name>,

            "profile_image_url":<Profile Image url>,

            "gender":<Gender>,

            "redeemed_points":<Redeemed Points>,

            "available_points":<Available Points>,

            "loyalty_level_id":<Loyalty Level>,

            "loyalty_lifetime_level_id":"platinum_lifetime",

            "merchant_uid":<User ID provided by merchant>

            },

"success":true

}


10.2 Error Responses

 

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

 

{

 "reason":"Invalid User",

 "success":false

}


Example:


This is an example of a curl request:


curl–X PUT --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data "loyalty_level=<loyalty-level>"https://api.shopsocially.com/v2/loyalty/users/akj89q0

 

When such a request is made, a JSON object like the one below will be returned:


{

"data":{

             "user_id":6176be2d5e,

             "user_email": Rohit@shopsocially.com,

             "first_name":Rohit,

             "last_name": B,

             "profile_image_url": http://....,

             "gender":"male",

             "redeemed_points": 1000,

             "available_points": 200,

             "loyalty_level_id": "platinum",

             "loyalty_lifetime_level_id":"platinum_lifetime",

             "merchant_uid":"akj89q0"

             },

"success":true

}



11. Get User Transactions
 
This will return information about the transactions done (points earned / redeemed ) by any user. User's email ID will be used to search and return user specific information.
 
Type of Request: GET
Endpoint: /loyalty/users/{user_email}/transactions

Table 9: Post Request Parameters
Parameter Value Is Required Description
from_date String Value (MM/DD/YYYY) Required The start date.
to_date String Value (MM/DD/YYYY) Required The end date.
points_status List of Strings (['pending','auto_approved','approved',
'auto_rejected','rejected', 'exhausted', 'expired'])
Optional The status of the transaction i.e pending, auto_approved, approved, auto_rejected, rejected.

Note:
Exhausted are awarded points which are redeemed by user.
 
Expired points are awarded points which user has not redeemed within validity period.
start_index Number (Defaults to zero) Optional The index from where data needs to be fetched.


11.1 Response Fields for JSON response

{
"data": {
             "total": 9,
             "next_start_index": 10,
             "transactions": [
             {
             "points_status": "approved",
             "points_used": 0,
             "available_points": 22,
             "points_expired": 0,
             "created_time": "14-Jan-2016 06:33:22",
             "updated_time": "14-Jan-2016 06:33:22",
             "id": "569741320daac146edac90c0",
             "user_id": "54b3b13e0daac1321e07ce1f",
             "points_expiration_date": "14-Mar-2016 06:33:22",
             "approved_by": null,
             "qualified_points": true,
             "redemption_value": null,
             "activity_id": "shared_photo_via_desktop_or_mobile",
             "user_first_name": "Ezio",
             "order_id": "1452749387649368175",
             "reason": null,
             "points_deducted": 0,
             "merchant_id": "137692186f3cfaf9fc0839d8da0934f6",
             "redemptions_list": null,
             "approved_time": "14-Jan-2016 06:33:22",
             "redemption_name": null,
             "auto_approval_date": "",
             "transaction_type": "award",
             "user_last_name": "Auditore",
             "coupon_code": null,
             "points": 22,
             "redemption_id": null,
             "activity_name": "Shared Photo via Mobile or Desktop",
             "user_email": "subhrajyoti@shopsocially.com"
             },
             {
             "points_status": "approved",
             "points_used": 0,
             "available_points": 55,
             "points_expired": 0,
             "created_time": "14-Jan-2016 06:33:13",
             "updated_time": "14-Jan-2016 06:33:13",
             "id": "569741290daac146edac90bf",
             "user_id": "54b3b13e0daac1321e07ce1f",
             "points_expiration_date": "14-Mar-2016 06:33:13",
             "approved_by": null,
             "qualified_points": true,
             "redemption_value": null,
             "activity_id": "shared_photo_via_desktop_or_mobile",
             "user_first_name": "Ezio",
             "order_id": "1452749387649368175",
             "reason": null,
             "points_deducted": 0,
             "merchant_id": "137692186f3cfaf9fc0839d8da0934f6",
             "redemptions_list": null,
             "approved_time": "14-Jan-2016 06:33:13",
             "redemption_name": null,
             "auto_approval_date": "",
             "transaction_type": "award",
             "user_last_name": "Auditore",
             "coupon_code": null,
             "points": 55,
             "redemption_id": null,
             "activity_name": "Shared Photo via Mobile or Desktop",
             "user_email": "subhrajyoti@shopsocially.com"
             },
             {
             "points_status": "approved",
             "points_used": 0,
             "available_points": 55,
             "points_expired": 0,
             "created_time": "14-Jan-2016 06:32:47",
             "updated_time": "14-Jan-2016 06:32:47",
             "id": "5697410f0daac146edac90be",
             "user_id": "54b3b13e0daac1321e07ce1f",
             "points_expiration_date": "14-Mar-2016 06:32:47",
             "approved_by": null,
             "qualified_points": true,
             "redemption_value": null,
             "activity_id": "shared_photo_via_desktop_or_mobile",
             "user_first_name": "Ezio",
             "order_id": null,
             "reason": null,
             "points_deducted": 0,
             "merchant_id": "137692186f3cfaf9fc0839d8da0934f6",
             "redemptions_list": null,
             "approved_time": "14-Jan-2016 06:32:47",
             "redemption_name": null,
             "auto_approval_date": "",
             "transaction_type": "award",
             "user_last_name": "Auditore",
             "coupon_code": null,
             "points": 55,
             "redemption_id": null,
             "activity_name": "Shared Photo via Mobile or Desktop",
             "user_email": "subhrajyoti@shopsocially.com"
             }
             ],
             "more": false
             },
"success": true
}

Example:

This is an example of a curl request:

 
When such a request is made, a JSON object like the one below will be returned:
 
{
"data":{
            "total": 250
            "next_start_index": 11,
            "transactions":[
            {
            "activity_id":"Made_a_Purchase",
            "activity_name":"Made a Purchase",
            "user_id":"6176be2d5e",
            "user_first_name":"Rohit",
            "user_last_name":"B",
            "user_email":"Rohit@shopsocially.com",
            "redemption_id":"",
            "redemption_name":,
            "id":"550ff099fa0eaa0767086968",
            "approved_time":"20-Mar-15 19:20:22",
            "auto_approval_date":"",
            "points_status":"approved",
            "transaction_type":"award",
             "coupon_code":"",
            "points": 100,
            "approved_by":"Jai",
            "created_time":"20-Mar-15 19:20:22",
            "updated_time":"30-Mar-15 19:20:22",
            "merchant_id":"3994293d288f628bb94adde076ab36b5",
            },….{}
            ],
            "more":true< This will be true when there are more records to be fetched>
            },
"success":true
}


12. Get All Activities
 
This can be used to view a list of all configured activities for which customers can earn loyalty points.
 
Type of Request: GET
Endpoint: /loyalty/activities
Get Request Parameters: No Request parameters for this API.

12.1 Response Fields for JSON response

{
"data":[
          {
           "activity_id":<Activity ID>,
           "updated_time":<Updated Time>,
           "max_award_frequency":<Max Award Frequency>,
           "terms_and_conditions":<Terms and Conditions>,
           "is_active":<Activity State(true/false)>,
           "ss_internal":<SS Activity(true/false)>,
           "approval_method":<Award Approval Method(immediate/manual/monthly)>,
           "points_per_activity":<Points per activity to be awarded to the user>,
           "bonus_multiplier":<Bonus Multiplier(to be multiplied to the passed points)>,
           "created_time":<Created Time>,
           "max_award_frequency_interval":<Max Award Frequency Interval>,
           "activity_name":<Activity Name>,
           "merchant_id":<Partner ID>,
           "activity_description":<Activity Description>,
           "id":<Activity Internal ID>,
           "activity_type":<Activity Type(fixed/bonus_multiplier)>
           },…{}
           ],
"success":true
}

12.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics:
 
{
 "reason":"authentication failure",
 "success":false
}
 
Example:

This is an example of a curl request:
When such a request is made, a JSON object like the one below will be returned:
 
{
"data":[
          {
           "activity_id":Referred_via_facebook,
           "updated_time":Monday, 30-Mar-15 19:20:22 UTC,
           "max_award_frequency": 10,
           "terms_and_conditions":,
           "is_active": false,
           "ss_internal": false >,
           "approval_method": manually,
           "points_per_activity": 50,
           "bonus_multiplier":,
           "created_time":<Created Time>,
           "max_award_frequency_interval": day,
           "activity_name": Referred friend via facebook,
           "merchant_id": 3994293d288f628bb94adde076ab36b5,
           "activity_description": Referred friend via Facebook,
           "id":550ff099fa0eaa0767086968,
           "activity_type":fixed
           },…{}
           ],
"success":true
}
Go to top
13. Create Activity

This can be used to create a new activity which will earn loyalty points for customers.

Type of Request: POST
Endpoint: /loyalty/activities

Table 10: POST Create Activity Request Parameters
Parameter Value Is Required Description
max_award_frequency Number  Required
The maximum number of times a user will be awarded points.
is_active Boolean(true/false) Optional(defaults to false) Should the activity be active or paused.
approval_method String Value (immediate/manual/monthly) Required User transaction approval method.
points_per_activity Number Optional(defaults to 0) Fixed number of points to be awarded for an activity.
bonus_multiplier Decimal Optional(defaults to 1) Multi plication factor to award points instead of awarding fixed points.
max_award_frequency_interval String Value(day, week, month, year, lifetime) Required The time interval constraint to the max_award_frequency number.
 activity_name  String Value  Required  Name of the Activity.
 activity_description  String Value  Required  Description of the activity.
 activity_type  String Value (fixed/bonus_multiplier)  Required  Should the activity award fixed number of points or use a multiplier.
 activity_id  String Value  Required  The activity id of the required Activity.


13.1 Response Fields for JSON response


{

"data": {

             "activity_id": <activity_id>,

             "activity_name": <activity_name>,

             "updated_time": <updated_time>,

             "max_award_frequency": <max_award_frequency>,

             "is_active": <is_active>,

             "points_expiration_period": <points_expiration_period>,

             "loyalty_activity_img": <loyalty_activity_img>,

             "id": <id>,

             "approval_method": <approval_method>,

             "qualified_points": <qualified_points>,

             "ss_internal": <ss_internal": false>,

             "points_per_activity": <points_per_activity>,

             "bonus_multiplier": <bonus_multiplier>,

             "created_time": <created_time>,

             "max_award_frequency_interval": <max_award_frequency_interval>,

             "bonus_multiper": <bonus_multiper>,

             "merchant_id": <merchant_id>,

             "activity_description": <activity_description>,

             "points_earning_url": <points_earning_url>,

             "activity_type": <activity_type>,

             },

"success": true

}


13.2 Error Responses


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

{

   "reason":"missing parameters",

   "success":false

}


Example:


Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.

An example curl request will look like this:


curl –X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " max_award_frequency = 10" --data " is_active = False" --data " approval_method = immediately--data " points_per_activity = 100--data " bonus_mutliplier = ‘’--data " max_award_frequency_interval = day --data " activity_name = emailsubscriber--data " activity_description = subscribe to newsletter--data " activity_type = fixed--data " activity_id = email_subscriber https://api.shopsocially.com/v2/loyalty/activities


You can replace the request parameters in the above request and run it from the command line to see the response. 


An example response will look like the one below:


{

"data": {

             "activity_id": "share_via_email_API",

             "activity_name": "share_via_email_API",

             "updated_time": "12-Feb-2016 12:36:56",

             "max_award_frequency": 2,

             "is_active": true,

             "points_expiration_period": 0,

             "loyalty_activity_img": "https://d1qbqkkh49kht1.cloudfront.net/c6dada872a795aafe92c30964f384470.png",

             "id": "56bdd1e88033721c45b1729f",

             "approval_method": "immediate",

             "qualified_points": true,

             "ss_internal": false,

             "points_per_activity": 100,

             "bonus_multiplier": 1,

             "created_time": "12-Feb-2016 12:36:56",

             "max_award_frequency_interval": "day",

             "bonus_multiper": "1.5",

             "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",

             "activity_description": "grab_it",

             "points_earning_url": null,

             "activity_type": "fixed"

             },

"success": true

}



14. Get Activity

This can be used to view details about any activity. The activity ID will be used to fetch this data.

Type of Request: GET
Endpoint: /loyalty/activities/{activity_id}
GET Request Parameters: No request parameters required.

14.1 Response Fields for JSON response

{
"data": {
             "activity_name": <activity_name>,
             "activity_id": <activity_id>,
             "updated_time": <updated_time>,
             "max_award_frequency": <max_award_frequency>,
             "is_active": <is_active>,
             "loyalty_activity_img": <loyalty_activity_img>,
             "ss_internal": <ss_internal>,
             "approval_method": "immediate",
             "qualified_points": true,
             "points_per_activity": <points_per_activity>,
             "bonus_multiplier": <bonus_multiplier>,
             "created_time": <created_time>,
             "max_award_frequency_interval": <max_award_frequency_interval>,
             "merchant_id": <merchant_id>,
             "activity_description": <activity_description>,
             "id": <id>,
             "points_earning_url": <points_earning_url>,
             "activity_type": <activity_type>,
             },
"success": true
}

14.2 Error Responses

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

{
   "reason":"Invalid Activity ID",
   "success":false
}

Example:

Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
This is an example of a curl request:

curl -X GET --header "partner-id:<your-partner-id>" --header "api-key:<your-api-key>" https://api.shopsocially.com/v2/loyalty/activities/{activity_id}
You can replace your partner ID, API key and activity _id in the above request and run it from the command line to see the response. 

An example response will look like the one below:

{
"data":{
            "activity_id":”email_subscriber”,
            "updated_time":”Monday, 30-Mar-15 19:20:22 UTC”,
            "max_award_frequency":10,
            "is_active":false,
            "ss_internal":false,
            "approval_method":”immediate”,
            "points_per_activity":100,
            "bonus_multiplier":,
            "created_time":”Monday, 30-Mar-15 19:20:22 UTC”,
            "max_award_frequency_interval":”day”,
            "activity_name":”email subscriber”,
            "merchant_id":”3994293d288f628bb94adde076ab36b5”,
            "activity_description":”subscribe to newsletter”,
            "id":”550ff099fa0eaa0767086968”,
            "activity_type":”fixed”
            },
"success":true
}


15. Update Activity

An activity configuration can be updated using the Activity ID.


Type of Request: PUT
Endpoint: /loyalty/activities/{activity_id}

Table 11: POST Update Activity Request Parameters
Parameter Value Description
max_award_frequency Number The maximum number of times a user will be awarded points.
is_active Boolean(true/false) Should the activity be active or paused.
approval_method String Value (immediate/manual/monthly) User transaction approval method.
points_per_activity Number Fixed number of points to be awarded for an activity.
bonus_multiplier Decimal Multiplication factor to award points instead of awarding fixed points.
max_award_frequency_interval String Value(day, week, month, year, lifetime) The time interval constraint to the max_award_frequency number.
activity_name String Value Name of the Activity.
activity_description String Value Description of the activity.
activity_type String Value (fixed/bonus_multiplier) Should the activity award fixed number of points or use a multiplier.

15.1 Response Fields for JSON response


{

  "data": {

               "activity_name": <activity_name>,

               "activity_id": <activity_id>,

               "updated_time": <updated_time>,

               "max_award_frequency": <max_award_frequency>,

               "is_active": <is_active>,

               "loyalty_activity_img": <loyalty_activity_img>,

               "ss_internal": <ss_internal>,

               "approval_method": <approval_method>,

               "qualified_points": <qualified_points>,

               "points_per_activity": <points_per_activity>,

               "bonus_multiplier": <bonus_multiplier>,

               "created_time": <created_time>,

               "max_award_frequency_interval": <max_award_frequency_interval>,

               "merchant_id": <merchant_id>,

               "activity_description": <activity_description>,

               "id": <id>,

               "points_earning_url": <points_earning_url>,

               "activity_type": <activity_type>,

               },

  "success": true

}


15.2 Error Responses


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

{

   "reason":"Invalid Activity ID",

   "success":false

}


Example:


Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.


An example curl request will look like this:


curl –X PUT --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " max_award_frequency = 10" --data " is_active = False" --data " approval_method = immediately--data " points_per_activity = 100--data " bonus_mutliplier = ‘’--data " max_award_frequency_interval = day --data " activity_name = emailsubscriber--data " activity_description = subscribe to newsletter--data " activity_type = fixed—data https://api.shopsocially.com/v2/loyalty/activities


You can replace the request parameters in the above request and run it from the command line to see the response. 


An example response will look like the one below:


{

  "data": {

               "activity_id": "connected_via_facebook",

               "updated_time": "15-Feb-2016 09:41:16",

               "max_award_frequency": 2,

               "is_active": false,

               "loyalty_activity_img":

               "https://d1qbqkkh49kht1.cloudfront.net/c6dada872a795aafe92c30964f384470.png",

               "ss_internal": true,

               "approval_method": "immediate",

               "qualified_points": true,

               "points_per_activity": 20,

               "bonus_multiplier": 1,

               "created_time": "11-Aug-2015 13:25:30",

               "max_award_frequency_interval": "lifetime",

               "activity_name": "Connected via Facebook",

               "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",

               "activity_description": "When someone shares profile via facebook connect",

                "id": "55c9f7ca8033720ef8fd95b2",

               "points_earning_url": null,

               "activity_type": "fixed"

               },

"success": true

}



16. Get All Redemptions

View a list of all the redemption options that are currently configured.

Type of Request: GET
Endpoint: /loyalty/redemptions
GET Request Parameters: No GET request parameters required.

16.1  Response Fields for JSON response

{
  "data": [
             {
             "redemption_name": <redemption_name>,
             "updated_time": <updated_time>,
             "loyalty_redemption_card_img": <loyalty_redemption_card_img>,
             "redemption_value": <redemption_value>,
             "giftcard_description": <giftcard_description>,
             "terms_and_conds_text": <terms_and_conds_text>,
             "is_active": <is_active>,
             "enable_coupon_based_incentive": <enable_coupon_based_incentive>,
             "allowed_redeem_points": <allowed_redeem_points>,
             "associated_levels": <associated_levels>,
             "send_redemption_email": <send_redemption_email>,
             "redemption_id": <redemption_id>,
             "redemption_instructions": <redemption_instructions>,
             "created_time": <created_time>,
             "coupon_expiry": <coupon_expiry>,
             "redemption_email_subject": <redemption_email_subject>,
             "merchant_id": <merchant_id>,
             "id": <id>,
             "redemption_email_html": <redemption_email_html>,
             },
             ......
             ],
  "success": true
}

16.2 Error Responses 

In case of errors, a JSON object is returned with the following semantics:
{
   "reason":"authentication failure",
   "success":false
}

Example:

Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
This is an example of a curl request:

curl -X GET --header "partner-id:<your-partner-id>" --header "api-key:<your-api-key>" https://api.shopsocially.com/v2/loyalty/redemptions

You can replace your partner ID and API key in the above request and run it from the command line to see the response. An example response will look like the one below:

{
"data":{
           "total": 15,
           "redemptions":[
           {
           "giftcard_description":”$50 Gift Card”,
           "redemption_name":”$50 Gift card”,
           "terms_and_conds_text":”redeem code at checkout”,
           "is_active":false,
           "allowed_redeem_points": 1000,
           "redemption_value":”$50”,
           "updated_time":”Monday, 30-Mar-15 19:20:22 UTC”,
           "redemption_id":”$50_Gift_Card”,
           "merchant_id":”3994293d288f628bb94adde076ab36b5”,
           "created_time":”Monday, 30-Mar-15 19:20:22 UTC”,
           "coupon_expiry":”5/30/2015”,
           "id":"546cde4afa0eaa6aee5384b3"
           },…{}
           ],
           "more":true
           },
"success":true
}


17. Create Redemption


Create a new redemption option in the loyalty program.
Type of Request: POST
Endpoint: /loyalty/redemptions


Table 12: POST Create Redemption Request Parameters
Parameter Value Is Required Description
Redemption_id String Value Required Redemption ID.
redemption_name String Value Required The name of the redemption which will be displayed to the user.
is_active Boolean Value(true/false) Optional(defaults to false) Should the redemption option be active or paused.
allowed_redeem_points Number  Required
The number of points to be deducted when user redeems.
redemption_value Number Required The monetary value associated with the redemption.
giftcard_description String Value Required The description of the giftcard/ coupon which will be shown to the user.
terms_and_conds_text String Value Required The terms and conditions text users have to agree to at the time of redemption.
redemption_instructions String Value Optional The redemption instructions displayed to the users.
giftcard_coupon_codes String Value (comma separated) Required One time coupon codes to be issued when user redeems.
coupon_expiry String Value(DD-MMM-YYYY) Required The expiry date of the coupons.


17.1 Response Fields for JSON response

{
"data": {
             "redemption_name": <redemption_name>,
             "loyalty_redemption_card_img": <loyalty_redemption_card_img>,
             "redemption_value": <redemption_value>,
             "giftcard_description": <giftcard_description>,
             "terms_and_conds_text": <terms_and_conds_text>,
             "after_redemption_html": <after_redemption_html>,
             "is_active": <is_active>,
             "enable_coupon_based_incentive": <enable_coupon_based_incentive>,
             "allowed_redeem_points": <allowed_redeem_points>,
             "associated_levels": <associated_levels>,
             "updated_time": <updated_time>,
             "send_redemption_email": <send_redemption_email>,
             "redemption_id": <redemption_id>,
             "redemption_instructions": <redemption_instructions>,
             "merchant_id": <merchant_id>,
             "created_time": <created_time>,
             "coupon_expiry": <coupon_expiry>,
             "redemption_email_subject": <redemption_email_subject>,
             "giftcard_coupon_codes": "a,b,c,d",
             "id": "56bddb528033721c45b172a0",
             "redemption_email_html": <redemption_email_html>,
             },
  "success": true
}

17.2 Error Responses
In case of errors, a JSON object is returned with the following semantics:
{
   "reason":"missing parameters",
   "success":false
}

Example:

Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.

An example curl request will look like this:

curl –X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " redemption_ID = <redemption-id>" --data " redemption_name = <redemption-name>" --data " is_active = false--data " allowed_redeemp_points = 1000--data " redemption_value = $50--data " giftcard_description = <description>--data " terms_and_conds_text = <terms>--data " redemption_instructions = <instructions>--data " giftcard_coupon_codes = 50off1,50off2,50off3 --data " coupon_expiry = 30-May-2015 https://api.shopsocially.com/v2/loyalty/redemptions

You can replace the request parameters in the above request and run it from the command line to see the response. An example response will look like the one below:
{
  "data": {
               "redemption_name": "coupon_1k",                   
               "loyalty_redemption_card_img": "https://d1qbqkkh49kht1.cloudfront.net/ 
               b32b7803e9bbcf6b8e9b8d8ce1be7224.png",
               "redemption_value": "50",
               "giftcard_description": "1k points",
               "terms_and_conds_text": "check terms and conditions on site",
               "after_redemption_html": "<div class=\"coupon_code_div\">_COUPON_CODE_</div>
               <div style=\"margin-
               top: 15px;\"> A copy of the code has been emailed to _USER_EMAIL_.</div>",
               "is_active": true,
               "enable_coupon_based_incentive": true,
               "allowed_redeem_points": 1000,
               "associated_levels": [
               "all"
               ],
               "updated_time": "12-Feb-2016 13:17:06",
               "send_redemption_email": true,
               "redemption_id": "coupon_1k",
               "redemption_instructions": null,
               "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",
               "created_time": "12-Feb-2016 13:17:06",
               "coupon_expiry": "10-Apr-2016",
               "redemption_email_subject": "Redemption Confirmation Receipt - _MERCHANT_NAME_ Loyalty Program",
               "giftcard_coupon_codes": "a,b,c,d",
               "id": "56bddb528033721c45b172a0",
               "redemption_email_html": "<div style=\"border:solid 1px rgba(0,0,0,0.2);font-family:'Source Sans Pro',                    'Helvetica Neue', 'Lucida Sans', sans-serif;\"><img
               style=\"width:100%\">
               <div style=\"text-align:left;margin-top:10px;font-size: 15px;padding:0px 30px 0px 30px\">Hi,<br>
               <div style=\"margin-top: 10px;\">You have redeemed _POINTS_REDEEMED_
               loyalty points from your account at <a href=\"_MERCHANT_WEB_URL_\" target=\"_blank\"
               >_MERCHANT_NAME_</a>.<br><br><a href=\"_USER_DASHBOARD_URL_
               \" target=\"_blank\">Click here</a> to log in and check your loyalty points status
               and to redeem more points.</div><div style=\"text-align:left;margin-top: 15px;font-size:15px;\
               ">Thank you.<br><br>Thanks,<br>_MERCHANT_NAME_ Team<br><br></div></div>
               style=\"width:100%\">
               },
"success": true
}


18. Get Redemption


View details about a particular redemption option using the Redemption Option ID.


Type of Request: GET
Endpoint: /loyalty/redemptions/{redemption_id}

Table 13: GET Redemption Request Parameters
Parameter Value Description
redemption_id String Value The redemption id of the required Redemption.


18.1 Response Fields for JSON response

{
  "data": {
               "redemption_name": <redemption_name>,
               "loyalty_redemption_card_img": <loyalty_redemption_card_img>,
               "redemption_value": <redemption_value>,
               "giftcard_description": <giftcard_description>,
               "terms_and_conds_text": <terms_and_conds_text>,
               "after_redemption_html": <after_redemption_html>,
               "is_active": <is_active>,
               "enable_coupon_based_incentive": <enable_coupon_based_incentive>,
               "allowed_redeem_points": <allowed_redeem_points>,
               "associated_levels": <associated_levels>,
               "updated_time": <updated_time>,
               "send_redemption_email": <send_redemption_email>,
               "redemption_id": <redemption_id>,
               "redemption_instructions": <redemption_instructions>,
               "merchant_id": <merchant_id>,
               "created_time": <created_time>,
               "coupon_expiry": <coupon_expiry>,
               "redemption_email_subject": <redemption_email_subject>,
               "giftcard_coupon_codes": <giftcard_coupon_codes>, "
               "id": <id>,
               "redemption_email_html": <redemption_email_html>,
               },
"success": true
}

18.2 Error Responses

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

{
   "reason":"Invalid Redemption ID",
   "success":false
}

Example:

Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
This is an example of a curl request:

curl -X GET --header "partner-id:<your-partner-id>" --header "api-key:<your-api-key>" https://api.shopsocially.com/v2/loyalty/redemptions/{redemption_id}
You can replace your partner ID, API key and redemption_id in the above request and run it from the command line to see the response. 

An example response will look like the one below:

{
"data":{
            "giftcard_description":“$50 Gift Card”,
            "terms_and_conds_text":”redeem code at checkout”,
            "redemption_name":”$50 Gift card”,
            "is_active":false,
            "allowed_redeem_points": “1000”,
            "redemption_value":“$50”,
            "updated_time":”30-Mar-15 19:20:22 UTC”,
            "redemption_id":“$50_Gift_Card”,
            "redemption_instructions":”redeem code at checkout”,
            "merchant_id":“3994293d288f628bb94adde076ab36b5”,
            "created_time":“30-Mar-15 19:20:22 UTC”,
            "coupon_expiry":“30-May-2015”,
            "giftcard_coupon_codes":”50off,50off2,50off3”,
            "id":”546cde4afa0eaa6aee5384b3”
            },
"success":true
}


19. Update Redemption

Update any of the configured redemption options using the Redemption option ID.


Type of Request: PUT
Endpoint: /loyalty/redemptions/{redemption_id}

Table 14: PUT Update Redemption Request Parameters
Parameter Value Description
redemption_name String Value The name of the redemption which will be displayed to the user.
is_active Boolean Value(true/false) Should the redemption option be active or paused.
allowed_redeem_points Number The number of points to be deducted when user redeems.
redemption_value String Value The monetary value associated with the redemption.
giftcard_description String Value The description of the giftcard/ coupon which will be shown to the user.
terms_and_conds_text String Value The terms and conditions text users have to agree to at the time of redemption.
redemption_instructions String Value The redemption instructions displayed to the users.
giftcard_coupon_codes String Value (comma separated) One time coupon codes to be issued when user redeems.
coupon_expiry String Value (DD-MMM-YYYY) The expiry date of the coupons.


19.1 Response Fields for JSON response


{

  "data": {

               "loyalty_redemption_card_img": <loyalty_redemption_card_img>,

               "redemption_value": <redemption_value>,

               "giftcard_description": <giftcard_description>,

               "terms_and_conds_text": <terms_and_conds_text>,

               "after_redemption_html": <after_redemption_html>,

               "redemption_name": <redemption_name>,

               "is_active": <is_active>,

               "enable_coupon_based_incentive": <enable_coupon_based_incentive>,

               "allowed_redeem_points": <allowed_redeem_points>,

               "associated_levels": <associated_levels>,

               "updated_time": <updated_time>,

               "send_redemption_email": <send_redemption_email>,

               "redemption_id": <redemption_id>,

               "redemption_instructions": <redemption_instructions>,

               "merchant_id": <merchant_id>,

               "created_time": <created_time>,

               "coupon_expiry": <coupon_expiry>,

               "redemption_email_subject": <redemption_email_subject>,

               "giftcard_coupon_codes": <giftcard_coupon_codes>,

               "id": <id>,

               "redemption_email_html": <redemption_email_html>,

               },

  "success": true

}


19.2 Error Responses


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

{

   "reason":"Invalid Redemption ID",

   "success":false

}


Example:


Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.

An example curl request will look like this:


curl –X PUT --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " redemption_name = <redemption-name>" --data " is_active = false--data " allowed_redeem_points = 1000--data " redemption_value = $50--data " giftcard_description = <description>--data " terms_and_conds_text = <terms>--data " redemption_instructions = <instructions>--data " giftcard_coupon_codes = 50off1,50off2,50off3 --data " coupon_expiry = 30-May-2015 https://api.shopsocially.com/v2/loyalty/redemptions/$50_Gift_Card


You can replace the request parameters in the above request and run it from the command line to see the response. An example response will look like the one below:


{

    "data": {

                 "loyalty_redemption_card_img":

                 "https://d1qbqkkh49kht1.cloudfront.net/b32b7803e9bbcf6b8e9b8d8ce1be7224.png",

                 "redemption_value": "YES",

                 "giftcard_description": "Redeem It",

                 "terms_and_conds_text": "The above code may be used as per terms of usage.",

                 "after_redemption_html": "<div

                 class=\"coupon_code_div\">_COUPON_CODE_</div><div

                 style=\"margin-top: 15px;\"> A copy of the code has been emailed to _USER_EMAIL_.</div>",

                 "redemption_name": "test_coupon",

                 "is_active": true,

                 "enable_coupon_based_incentive": true,

                 "allowed_redeem_points": 1,

                 "associated_levels": [

                 "all"

                 ],

                 "updated_time": "15-Feb-2016 09:14:42",

                 "send_redemption_email": true,

                 "redemption_id": "testcoupon",

                 "redemption_instructions": "Please visit <a href=\"_MERCHANT_WEB_URL_\"

                  target=\"_blank\">_MERCHANT_NAME_</a> and apply the code above at checkout.",

                 "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",

                 "created_time": "03-Sep-2015 06:51:35",

                 "coupon_expiry": "21-Nov-2015",

                 "redemption_email_subject": "Redemption Confirmation Receipt - _MERCHANT_NAME_

                  Loyalty Program",

                 "giftcard_coupon_codes":

                 "A1,B1,C1,D1,E1,F1,G1,H1,I1,J1,K1,L1,M1,O1,P1,Q1,R1,S1,T1,U1,V1,W1,X1,Y1,Z1",

                 "id": "55e7edf78033723499e54927",

                 "redemption_email_html": "<div style=\"border:solid 1px rgba(0,0,0,0.2);

                  font-family:'Source Sans Pro', 'Helvetica Neue', 'Lucida Sans',sans-serif;\">

                  <img src=\"https://d1qbqkkh49kht1.cloudfront.net/c66c2dc1d96e2ac46b9722b1a2524c10.png\"

                  style=\"width:100%\"><div style=\"text-align:left;margin-top:10px;font-size:15px;padding:

                  0px 30px 0px 30px\">Dear _USER_NAME_ ,<br>You redeemed points from the _MERCHANT_NAME_

                  loyalty program.

                  <br>This email confirms your redemption transaction.<br><br>

                  Thanks for being a _MERCHANT_NAME_ customer.

                  </div><div style=\

                  "text-align:center;height: 270px;background:

                  #f9f8f3;margin-left: 30px; margin-right:

                  30px; margin-top: 10px;margin-bottom: 30px;padding:

                  10px;border-radius: 10px;\"><div style=\

                  "font-size: 16px;font-weight:bold;margin-top: 20px;\"

                  >CONGRATULATIONS ! HERE'S YOUR REWARD</div>

                  <div style=\"font-size: 18px;font-weight:bold;margin-top: 10px;\"

                  >_REDEMPTION_OPTION_NAME_</div>

                  <div style=\"font-size: 14px;color: rgba(0,0,0,0.4);margin-top: 5px;\"

                  >_POINTS_REDEEMED_ points have been deducted.</div><div style=\

                  "text-align: center;padding:

                  0px 116px;margin-top: 15px;\"><div style=\"border:

                  dashed 1px #30c3c7;color: #30c3c7;font-size:

                  16px; font-weight:bold;padding: 5px;\"> _COUPON_CODE_ </div></div>

                  <div style=\"margin-top:

                  15px;text-transform: uppercase;font-size: 13px;\"

                  >REDEMPTION INSTRUCTIONS</div><div style=\

                  "font-size:13px;\">_REDEMPTION_INSTRUCTIONS_</div><div style=\

                  "margin-top: 15px;font-size: 13px;\

                  ">TERMS AND CONDITIONS</div><div style=\"font-size:

                  10px;\">_TERMS_</div></div></div>

                  },

"success": true

}



20. Get All Loyalty Levels

View a list of all the loyalty levels that are currently configured .

Type of Request: GET
Endpoint: /loyalty/levels
GET Request Parameters: No GET request parameters required.

20.1 Response Fields for JSON response

{
  "data": [
             {
               "merchant_id": <merchant_id>,
               "level_description": <level_description>,
               "level_position": <level_position>,,
               "level_id": <level_id>,
               "is_active": <is_active>,
               "level_bonus_multiplier": <level_bonus_multiplier>,
               "level_minimum_points": <level_minimum_points>,
               "is_default": <is_default>,
               "updated_time": <updated_time>,
               "created_time": <created_time>,
               "level_name": <level_name>,
               "level_type": <level_type>,
               "id": <id>,
               },
               .....
              ],
"success": true
}

20.2 Error Responses

In case of errors, a JSON object is returned with the following semantics:
{
   "reason":"authentication failure",
   "success":false
}

Example:

Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
This is an example of a curl request:

curl -X GET --header "partner-id:<your-partner-id>" --header "api-key:<your-api-key>" https://api.shopsocially.com/v2/loyalty/levels
You can replace your partner ID and API key in the above request and run it from the command line to see the response. An example response will look like the one below:

{
  "data": [
             {
              "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",
              "level_description": "3.3k",
              "level_position": 9,
              "level_id": "period_3.3_k",
              "is_active": true,
              "level_bonus_multiplier": 2,
              "level_minimum_points": 3300,
              "is_default": false,
              "updated_time": "23-Sep-2015 13:39:19",
              "created_time": "23-Sep-2015 13:39:19",
              "level_name": "Period 3.3 k",
              "level_type": "period",
              "id": "5602ab878033724c8a28e9a0"
              },
              .....
             ],
"success": true
}


21. Create Loyalty Level


Create a new Loyalty Level.


Type of Request: POST
Endpoint: /loyalty/levels


Table 15: POST Create Loyalty Level Request Parameters
Parameter Value Is Required Description
level_id String Value Required The ID of the level.
level_name String Value Required The name of the level.
level_description String Value Required The description of the level.
is_active Boolean(true/false) Optional(defaults to false) Should the activity be active or paused.
level_type String Value (period/lifetime) Required Level Type of Loyalty.
level_position Number Required Order of the level.
level_minimum_points Number Required The minimum number of points needed to be at level.
level_bonus_multiplier Decimal Required Multiplication factor to award points.


21.1 Response Fields for JSON response


{

  "data": {

               "merchant_id": <merchant_id>,

               "level_description": <level_description>,

               "level_position": <level_position>,

               "level_id": <level_id>,

               "is_active": <is_active>,

               "level_bonus_multiplier": <level_bonus_multiplier>,

               "level_minimum_points": <level_minimum_points>,

               "is_default": <is_default>,

               "updated_time": <updated_time>,

               "created_time": <created_time>,

               "level_name": <level_name>,

               "level_type": <level_type>,

               "id": <id>,

               },

"success": true

}


21.2 Error Responses


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


{

   "reason":"missing parameters",

   "success":false

}


Example:


This is an example of a curl request:


curl –X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " level_id = <level-id>" --data " level_name = <level-name>" --data " is_active = false" --data " minimum_points = 5000" --data " level_type = <level-type>" --data " level_description = <description>" --data " bonus_multiplier = <bonus_multiplier> --data "https://api.shopsocially.com/v2/loyalty/levels


When such a request is made, a JSON object like the one below will be returned:


{

  "data": {

               "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",

               "level_description": "all star level for users",

               "level_position": 10,

               "level_id": "all_star_level",

               "is_active": true,

               "level_bonus_multiplier": 2.5,

               "level_minimum_points": 15000,

               "is_default": false,

               "updated_time": "12-Feb-2016 13:38:36",

               "created_time": "12-Feb-2016 13:38:36",

               "level_name": "all star level",

               "level_type": "lifetime",

               "id": "56bde05c8033721c45b172a1"

               },

"success": true

}



22. Update Loyalty Level

View a list of all the loyalty levels that are currently configured.

Type of Request: PUT
Endpoint: /loyalty/levels/{level_id}

Table 16: PUT Update Loyalty Level Request Parameters
Parameter Value Description
level_name String Value The name of the level.
level_description String Value The description of the level.
is_active Boolean(true/false) Should the activity be active or paused.
level_type String Value (period/lifetime) Level Type of Loyalty.
level_position Number Order of the level.
level_minimum_points Number The minimum number of points needed to be at level.
level_bonus_multiplier Decimal Multiplication factor to award points.


22.1 Response Fields for JSON response

{
  "data": {
               "merchant_id": <merchant_id>,
               "level_description": <level_description>,
               "level_position": <level_position>,
               "level_id": <level_id>,
               "is_active": <is_active>,
               "level_bonus_multiplier": <level_bonus_multiplier>,
               "level_minimum_points": <level_minimum_points>,
               "is_default": <is_default>,
               "updated_time": <updated_time>,
               "created_time": <created_time>,
               "level_name": <level_name>,
               "level_type": <level_type>,
               "id": <id>,
               },
"success": true
}

22.2 Error Responses

In case of errors, a JSON object is returned with the following semantics:
{
   "reason":"Invalid Level ID",
   "success":false
}

Example:

This is an example of a curl request:

curl–X PUT --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data " level_name = <level-name>" --data " is_active = false" --data " minimum_points = 5000" --data " level_type = <level-type>" --data " level_description = <description>" --data " bonus_multiplier = <bonus_multiplier>" https://api.shopsocially.com/v2/loyalty/levels/platinum_level

When such a request is made, a JSON object like the one below will be returned:

{
  "data": {
               "merchant_id": "c99ad71fcd6929dc9161b9b01781ce3a",
               "level_description": "all star level for users",
               "level_position": 10,
               "level_id": "all_star_level",
               "is_active": true,
               "level_bonus_multiplier": 2.5,
               "level_minimum_points": 15000,
               "is_default": false,
               "updated_time": "12-Feb-2016 13:42:49",
               "created_time": "12-Feb-2016 13:38:36",
               "level_name": "all star level",
               "level_type": "period",
               "id": "56bde05c8033721c45b172a1"
               },
"success": true 
}


23. Get Loyalty Level


View a list of all the loyalty levels that are currently configured.


Type of Request: GET
Endpoint: /loyalty/levels/{level_id}
GET Request Parameters: No GET request parameters are required.


23.1 Response Fields for JSON response


{

  "data": {

               "merchant_id": <merchant_id>,

               "level_description": <level_description>,

               "level_position": <level_position>,

               "level_id": <level_id>,

               "is_active": <is_active>,

               "level_bonus_multiplier": <level_bonus_multiplier>,

               "level_minimum_points": <level_minimum_points>,

               "is_default": <is_default>,

               "updated_time": <updated_time>,

               "created_time": <updated_time>,

               "level_name": <level_name>,

               "level_type": <level_type>,

               "id": <id>,

               },

"success": true

}


23.2 Error Responses


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


{

   "reason":"Invalid Level ID",

   "success":false

}


Example:


Below is an example of what the API request should look like and what the response looks like. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.

This is an example of a curl request:


curl -X GET --header "partner-id:<your-partner-id>" --header "api-key:<your-api-key>" https://api.shopsocially.com/v2/loyalty/levels/{level_id}


You can replace your partner ID, API key and level_id in the above request and run it from the command line to see the response. An example response will look like the one below:


{

  "data": {

               "merchant_id": <merchant_id>,

               "level_description": <level_description>,

               "level_position": <level_position>,

               "level_id": <level_id>,

               "is_active": <is_active>,

               "level_bonus_multiplier": <level_bonus_multiplier>,

               "level_minimum_points": <level_minimum_points>,

               "is_default": <is_default>,

               "updated_time": <updated_time>,

               "created_time": <updated_time>,

               "level_name": <level_name>,

               "level_type": "period",

               "id": "56bde05c8033721c45b172a1"

               },

"success": true

}



24. Return Order

This can be used to deduct points of a User when the user returns an order.

Type of Request: POST

Endpoint: /loyalty/transaction/return

Full URL: https://api.shopsocially.com/v2/loyalty/transaction/return


Table 17: Post Return order Request Parameters

Parameter Value Is Required Description
order_id String Value Required The order ID for which the return needs to be processed.
returned_amount  Number Optional
(If specified, the amount will be subtracted from the actual value of the order and remaining points will be awarded).
  • If returned_amount is not passed, it will be considered as complete order return. 
  • If returned_amount is specified and is a non-zero positive number, it will be processed as a partial return.


24.1 Response Fields for JSON response

{
"data": {
             "user_first_name": "Raijin",
             "user_id": "57cbd1b8b0207a0a6ab7905c",
             "auto_approval_date": "",
             "points_status": "pending_deduction",
             "returned_for_order_id": "Order Partially Returned",
             "transaction_type": "deduct",
             "user_last_name": "Thunderkeg",
             "reason": "Order Partially Returned",
             "points": 1,
             "user_email": "subhtestshop@gmail.com",
             "created_time": "06-Oct-2016 10:19:32",
             "updated_time": "06-Oct-2016 10:19:32",
             "partner_id": "137692186f3cfaf9fc0839d8da0934f6",
             "id": "57f62534b0207a09ef8a327f",
             "approved_time": "06-Oct-2016 10:19:32"
             },
"success": true
}

24.2 Error Responses
 
In case of errors, a JSON object is returned with the following semantics:

1.2.1 Invalid Order ID

{
  "reason": "Invalid Order ID",
  "success": false
}

24.2.2 Return amount is more than points available to deduct

{
  "reason": "Points to deduct is greater than points available to deduct for the Order ID",
  "success": false
}
Example:
Below is an example of the API request and the response. We show the example using the command-line tool curl but you can use any programming language you want to consume the API.
An example curl request will look like this:
curl–X POST --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" --data "order_id= <order id>" --data " returned_amount= <returned amount>" https://api.shopsocially.com/v2/loyalty/transaction/return


25. Summary

ShopSocially’s Loyalty Program API is a comprehensive set of calls required to build a complete loyalty program. This set caters to the needs of even the most sophisticated loyalty programs.