Overview
Welcome to the Zinrelo API documentation. You can use this API to access all our API endpoints, such as the Loyalty API, to build a common rewards program for all your sales channels.
We have language bindings in Shell and Python! You can view code examples in the area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Authentication
To authorize, use this code:
import requests
headers = {'partner-id': <your-partner-id>,
'api-key': <your-api-key>}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/transactions",
headers = headers)
curl -H "partner-id: <your-partner-id>"
-H "api-key: <your-api-key>"
"https://api.zinrelo.com/v1/loyalty/transactions"
The Zinrelo API exports sensitive data, so any call to the Zinrelo API needs to be authenticated.
For authenticating an API call, you have to send your Partner ID, and an API Key in the HTTP header of each API request.
To access Partner ID, and the API Key, please follow the steps given below:
- Login to your Merchant Center Console.
- Navigate to General > Settings, to find your Partner ID, and API Key.
- Send the keys in the HTTP header of each API request as given below :
'api-key': '<your-api-key'
'partner-id' : '<your-partner-id>'
Zinrelo API
Points
Award
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "user_email=bob@zinrelo.com"
--data "points_passed=100"
--data "activity_id=made_a_purchase"
--data "order_id=75a2726d13artibb10"
--data "reason=awarded points for missing order"
--data "tags=rich,royal"
"https://api.zinrelo.com/v1/loyalty/award"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {"user_email": "bob@zinrelo.com",
"points_passed": 100,
"activity_id": "made_a_purchase",
"order_id":"75a2726d13artibb10",
"reason":"awarded points for missing order",
"tags": "rich,royal"}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/award",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"user_email": "bob@zinrelo.com",
"last_name": "Baker",
"first_name": "Bob",
"activity_id": "made_a_purchase",
"activity_name": "Made a Purchase",
"transaction_type":"award",
"points": 100,
"points_status": "auto_approved",
"created_time": "30-Mar-16 19:20:22",
"reason": "awarded points for missing order",
"tags": ["rich","royal"]
},
"success":true
}
Award points to a user for any activity. Points will be awarded based on the user’s email address.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/award
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
user_email | string | Yes | The email of the user to whom points have to be awarded. |
points_passed | integer | No (if activity type is fixed) Yes (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 | Yes | 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 | No | 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 |
reason | string | No | The reason for which the points are being awarded to the user |
tags | string | No | List of tags to be assigned to the transaction as a comma-separated string |
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | The person’s email address |
last_name | string | The person’s last name |
first_name | string | The person’s first name |
activity_id | string | The id of the activity for which the points were awarded |
activity_name | string | The name of the activity for which the points were awarded |
transaction_type | string | This will always be “award” |
points | integer | The number of points awarded |
points_status | string | The status of the award transaction |
created_time | string | The time when the record was created |
reason | string | The reason for which the points are awarded to the user. |
tags | list | List of tags assigned to the transaction |
Purchase
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "user_email=bob@zinrelo.com"
--data "total=100"
--data "subtotal=80"
--data "order_id=75a2726d13artibb10"
--data "currency=USD"
--data "coupon_code=CODE101"
--data "tags=rich,royal"
--data 'products=[{"category": "Mugs",
"img_url": "https://cdn.website.com/product1/img.jpg",
"price": "80",
"product_id": "1234df",
"quantity": "1",
"tags": "Special, Coffee",
"title": "Snoozeberry Travel Mug",
"url": "http://www.website.com/product1.html"}]'
"https://api.zinrelo.com/v1/loyalty/purchase"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
products = [{"category": "Mugs",
"img_url": "https://cdn.website.com/product1/img.jpg",
"price": "80",
"product_id": "1234df",
"quantity": "1",
"tags": "Special, Coffee",
"title": "Snoozeberry Travel Mug",
"url": "http://www.website.com/product1.html"}]
payload = {"user_email": "bob@zinrelo.com",
"total":"100",
"subtotal":"80",
"order_id":"75a2726d13artibb10",
"currency":"USD",
"coupon_code":"CODE101",
"tags": "rich,royal",
"products":json.dumps(products)}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/purchase",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"user_email": "bob@zinrelo.com",
"last_name": "Baker",
"first_name": "Bob",
"activity_id": "made_a_purchase",
"activity_name": "Made a Purchase",
"transaction_type":"award",
"points": 100,
"points_status": "auto_approved",
"created_time": "30-Mar-16 19:20:22",
"tags": ["rich","royal"]
},
"success":true
}
Award points to a user for making a purchase. Points will be calculated based on the rules set in the purchase activity.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/purchase
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
user_email | string | Yes | The email of the user to whom points have to be awarded. |
total | string | Yes | Total order value. |
subtotal | string | Yes | Order value without shipping and taxes. |
order_id | string | Yes | Order ID of the purchase transaction. This ensures that points for a particular transaction are awarded only once. |
currency | string | No | Three letter currency code for your store. Defaults to USD. |
coupon_code | string | No | Coupon code used. |
tags | string | No | List of tags to be assigned to the transaction as a comma-separated string |
products | list | No | List of products bought. Product information should be passed in a specific format as shown in the sample code with the below parameters |
Products
Parameter | Type | Mandatory | Description |
---|---|---|---|
product_id | string | Yes | Unique product identifier |
price | string | Yes | Product price |
quantity | string | Yes | Quantity bought |
title | string | Yes | Title of the product |
url | string | Yes | Url of the product page |
img_url | string | No | Url of the product image |
category | string | No | Internal Product Category |
tags | string | No | Internal Product tags |
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | The person’s email address |
last_name | string | The person’s last name |
first_name | string | The person’s first name |
activity_id | string | The id of the activity for which the points were awarded |
activity_name | string | The name of the activity for which the points were awarded |
transaction_type | string | This will always be “award” |
points | integer | The number of points awarded |
points_status | string | The status of the award transaction.Status can be approved,auto_approved,cached or pending |
created_time | string | The time when the transaction was created |
tags | list | List of tags assigned to the transaction |
Redeem
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "user_email=bob@zinrelo.com"
--data "redemption_id=reward_d65bc"
--data "tags=rich,royal"
"https://api.zinrelo.com/v1/loyalty/redeem"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {"user_email": "bob@zinrelo.com",
"redemption_id": "reward_d65bc",
"tags": "rich,royal"}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/redeem",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data":{
"user_email": "bob@zinrelo.com",
"last_name": "Baker",
"first_name": "Bob",
"redemption_name": "$50 Gift Card",
"redemption_id" : "reward_d65bc",
"points": 1000,
"points_status": "redeemed",
"coupon_code": "GET50OFF",
"created_time": "03-May-17 19:20:22",
"tags": ["rich","royal"]
},
"success":true
}
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.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/redeem
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
user_email | string | Yes | The email of the user who wishes to redeem the points. |
redemption_id | string | Yes | The ID of the desired redemption option. The redemption ID is available in the merchant center. |
tags | string | No | List of tags to be assigned to the transaction as a comma-separated string |
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | The person’s email address |
last_name | string | The person’s last name |
first_name | string | The person’s first name |
redemption_id | string | The id of the redemption option chosen |
redemption_name | string | The name of the redemption chosen option |
points | integer | The number of points redeemed |
points_status | string | This will always be “redeemed” |
coupon_code | string | The coupon code to be used for successive transactions |
tags | list | List of tags assigned to the transaction |
created_time | string | The time when the record was created |
Deduct
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "user_email=bob@zinrelo.com"
--data "reason=invalid transaction"
--data "points_passed=1000"
--data "tags=rich,royal"
"https://api.zinrelo.com/v1/loyalty/users/deduct"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {"user_email": "bob@zinrelo.com",
"reason": "invalid transaction",
"points_passed": 1000,
"tags": "rich,royal"}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/users/deduct",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data":{
"user_email": "bob@zinrelo.com",
"first_name": "Bob",
"last_name": "Baker",
"points_status": "deducted",
"transaction_type": "deduct",
"available_points": 1500,
"reason": "invalid transaction",
"points": 1000,
"created_time": "30-Mar-15 19:20:22",
"tags": ["rich","royal"]
},
"success":true
}
Deduct points from a user’s available points. This deduction may not be related to redemption.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/users/deduct
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
user_email | string | Yes | The email of the user whose points are to be deducted. |
reason | string | Yes | The reason for deduction. |
points_passed | integer | Yes | The number of points to be deducted. |
tags | string | No | List of tags to be assigned to the transaction as a comma-separated string |
Response Body
Attribute | Type | Description |
---|---|---|
first_name | string | The person’s first name |
last_name | string | The person’s last name |
points_status | string | This will always be “deducted” |
transaction_type | string | This will always be “deduct” |
available_points | integer | The points available to the user after deduction |
reason | string | Reason for the deduction |
points | integer | The number of points deducted |
created_time | string | The time when the record was created |
user_email | string | The person’s email address |
tags | list | List of tags assigned to the transaction |
Transactions
Get all transactions
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/transactions?from_date=01/01/2016&to_date=31/12/2017&points_status=['approved']&start_index=0"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = { "from_date": "01/01/2016",
"to_date": "05/23/2017",
"points_status": '["approved"]',
"start_index": 7
}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/transactions",
headers = headers, params = payload)
The above command returns JSON structured like this:
{
"data":{
"total": 250,
"next_start_index":100,
"transactions":[{
"first_name": "bob",
"last_name": "baker",
"user_email": "bob@zinrelo.com",
"activity_name": "Purchase on website",
"transaction_type": "award",
"order_id": "12345ddfd67",
"points_status": "approved",
"points_passed": 100,
"points": 300,
"points_used": 0,
"redemption_name": null,
"redemption_value": null,
"approved_by": null,
"created_time": "09-May-2017 12:21:53",
"approved_time": "2017-05-09 12:21:53.138000",
"auto_approval_date": null,
"points_expiration_date": "2017-07-09 12:42:05.484000",
"additional_data": {
"zrl_products": [
{
"category": "trucks",
"product_id": "1235df",
"price": "5",
"product_points_per_quantity": 10,
"bonus_multiplier": 2,
"quantity": "1"
},
{
"category": "toys",
"product_id": "231235df",
"price": "5",
"product_points_per_quantity": 5,
"bonus_multiplier": 0,
"quantity": "1"
}
]
},
"returned_for_order_id": null
},
{...}],
"more":true
},
"success":true
}
Fetch list of all transactions in the given period
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/transactions
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
from_date | string | Yes | The start date (format is MM/DD/YYYY) |
to_date | string | Yes | The end date (format is MM/DD/YYYY) |
points_status | list of strings | No | The status of the transaction (pending/approved/ redeemed/rejected/ deducted/expired) |
start_index | integer | No | The index from where data needs to be fetched (defaults to 0) |
Response Body
Attribute | Type | Description |
---|---|---|
total | integer | total number of transactions |
next_start_index | integer | starting index of next batch of transactions |
transactions | list | list of transactions |
first_name | string | The person’s first name |
last_name | string | The person’s last name |
order_id | string | The order ID in case of a purchase transaction |
auto_approval_date | string | The time when transaction was auto approved |
points_status | string | Status of transaction (approved/auto_approved/exhausted/ pending/redeemed/deducted/ rejected/expired) |
points_used | integer | The number of points used for redeeming a reward |
redemption_value | string | Currency value of the redemption |
points_passed | integer | Corresponds to the order_subtotal passed during a purchase transaction |
points_expiration_date | string | The time when the points for the transaction expire if expiration is enabled |
redemption_name | string | Name of the redemption |
points | integer | The number of points involved in transaction |
approved_by | string | Name of admin who approved the transaction |
user_email | string | The person’s email address |
created_time | string | The time when the transaction was created |
activity_name | string | Name of the activity |
transaction_type | string | Type of transaction (award,deduct,redeem) |
additional_data | json | Details of the products bought in the purchase transaction |
approved_time | string | The time when transaction was approved |
returned_for_order_id | string | The order ID for which a return transaction has been processed |
Get User Transactions
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "from_date= 01/01/2016",
--data "to_date= 12/31/2016",
--data "points_status= ['approved']",
--data "start_index= 0",
"https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/transactions"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {
"from_date" : "01/01/2016",
"to_date" : "12/31/2016",
"points_status" : ['approved'],
"start_index" : 0,
}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/transactions",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"total": 1,
"next_start_index": 2,
"transactions": [{
"first_name": "bob",
"last_name": "baker",
"user_email": "bob@zinrelo.com",
"activity_name": "Purchase on website",
"transaction_type": "award",
"order_id": "12345ddfd67",
"points_status": "approved",
"points_passed": 100,
"points": 300,
"points_used": 0,
"redemption_value": null,
"redemption_name": null,
"approved_by": null,
"created_time": "09-May-2017 12:21:53",
"approved_time": "2017-05-09 12:21:53.138000",
"auto_approval_date": null,
"points_expiration_date": "2017-07-09 12:42:05.484000",
"additional_data": {
"zrl_products": [
{
"category": "trucks",
"product_id": "1235df",
"price": "5",
"product_points_per_quantity": 10,
"bonus_multiplier": 2,
"quantity": "1"
},
{
"category": "toys",
"product_id": "231235df",
"price": "5",
"product_points_per_quantity": 5,
"bonus_multiplier": 0,
"quantity": "1"
}
]
},
"returned_for_order_id": null
}],
"more": false
},
"success":true
}
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.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/users/{user_email}/transactions
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
from_date | string | Yes | The start date |
to_date | string | Yes | The end date |
points_status | string | No | Status of transaction to fetch (pending/approved/ redeemed/rejected/ expired/deducted) |
start_index | integer | No | The start index to fetch the data from (defaults to 0) |
Response Body
Attribute | Type | Description |
---|---|---|
total | integer | Total number of transactions for the user |
next_start_index | integer | Next index of record to fetch |
transactions | array | Array of transactions based on time range, filters and start_index |
more | boolean | Indicates if more number of transactions are available (true/false) |
Returns
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "order_id=ORDER101"
"https://api.zinrelo.com/v1/loyalty/transaction/return"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {"order_id": 'ORDER101'}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/transaction/return",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data":{
"user_email": "bob@zinrelo.com",
"last_name": "Baker",
"first_name": "Bob",
"points": 1000,
"points_status": "pending_deduction",
"returned_for_order_id": "ORDER101",
"reason": "Order Fully Returned",
"created_time": "30-Mar-16 19:20:22"
},
"success":true
}
Deduct points of a user when the user returns an order.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/transaction/return
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
order_id | string | Yes | The order ID for which the return needs to be processed. |
returned_amount | integer | No | If returned_amount is specified and is a non-zero positive number, it will be processed as a partial return. 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. |
returned_product_id | string | No | The ID for the product to be returned. |
quantity | integer | No | The number of products to be returned. |
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | The person’s email address |
last_name | string | The person’s last name |
first_name | string | The person’s first name |
points | integer | The number of points awarded |
points_status | string | The status of the award transaction |
returned_for_order_id | string | The order ID for which the return has been processed |
reason | string | The reason for returning the order |
created_time | string | The time when the record was created |
Users
Create User
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "first_name=bob"
--data "last_name=Baker"
--data "email=bob@zinrelo.com"
--data "uid=12345"
--data "dob=12/31/1992"
--data "tags=rich,royal"
"https://api.zinrelo.com/v1/loyalty/users"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {
"first_name" : "Bob",
"last_name" : "Baker",
"email" : "bob@zinrelo.com",
"uid" : "12345",
"dob": "12/31/1992",
"tags": "rich,royal"
}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/users",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"email":"bob@zinrelo.com",
"first_name":"Bob",
"last_name":"Baker",
"referral_code": "BOB12345"
},
"success":true
}
Create a new user for merchant.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/users
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
first_name | string | Yes | First name of the user |
last_name | string | Yes | Last name of the user |
string | Yes | Email of the user | |
uid | string | Yes | User ID of the user |
dob | string | No | Birthdate of user. Format is MM/DD/YYYY |
referral_code | string | No | Referral code of the friend who has referred the user to be created |
tags | string | No | List of tags to be assigned to the user as a comma-separated string |
Response Body
Attribute | Type | Description |
---|---|---|
string | Email of the user | |
first_name | string | First name of the user |
last_name | string | Last name of the user |
referral_code | string | Referral code of the new user created |
Get All Users
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/users?from_date=01/01/2016&to_date=12/31/2016&start_index=0&count=1000"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = json.dumps({
"from_date" : "01/01/2016",
"to_date" : "12/31/2016",
"start_index" : 0,
"count" : 1000
})
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/users",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"total_loyalty_users":1,
"loyalty_users": [{
"last_name": "Baker",
"first_name": "Bob",
"user_email": "bob@zinrelo.com",
"address_line1": "H1-201,Persian Drive",
"address_line2": "Suite #101",
"city": "Sunnyvale",
"zipcode": "94089",
"state": "CA",
"country": "United States",
"phone_country_code": "+1",
"phone_number": "66656324213",
"referral_code": "BOB1234",
"referral_url": "https://test.zinrelo.com/raf/BOB1234",
"uid": "user123",
"has_opted_out": false,
"referrer_email": "",
"dob": "12/12/1988",
"loyalty_enroll_time": "10/20/2017",
"loyalty_tier_name": "Platinum",
"loyalty_tier_id": "zrl_platinum",
"tier_details": {
"period_start": "01/01/2019",
"points": 6100,
"period_end": "12/31/2019"
},
"user_id": "user123",
"available_points": 5900,
"redeemed_points": 200,
"awarded_points": 6100,
"pending_points": 0,
"expiration_schedule": [
{
"expiration_date": "18-Jan-2020 11:17:12",
"points": 6100
}
]
}],
"more":false
},
"success":true
}
This will get all the users enrolled in the loyalty program.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/users
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
from_date | string | No | The start date |
to_date | string | No | The end date |
filter_by | string | No | Filters to be applied along with from_date and to_date. Accepted values: ‘enrollment_date’ , 'last_activity_date |
start_index | integer | No | The start index to fetch the data from (defaults to 0) |
count | integer | No | Number of records to fetch (defaults to 1000) |
Response Body
Attribute | Type | Description |
---|---|---|
next_start_index | integer | Next index of record to fetch |
total_loyalty_users | integer | Total number of loyalty users for this merchant |
loyalty_users | array | Array of users based on time range, filters and start_index |
more | boolean | Indicates if more number of users are available (true/false) |
Get User
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com",
headers = headers)
The above command returns JSON structured like this:
{
"data": {
"last_name": "Baker",
"first_name": "Bob",
"user_email": "bob@zinrelo.com",
"dob": "12/12/1988",
"address_line1": "H1-201,Persian Drive",
"address_line2": "Suite #101",
"city": "Sunnyvale",
"zipcode": "94089",
"state": "CA",
"country": "United States",
"phone_country_code": "+21",
"phone_number": "66656324213",
"referral_code": "BOB1234",
"referral_url": "https://test.zinrelo.com/raf/BOB1234",
"referrer_email": "",
"uid": "user123",
"loyalty_enroll_time": "01/18/2019",
"loyalty_tier_id": "zrl_platinum",
"loyalty_tier_name": "Platinum",
"tier_details": {
"period_start": "01/01/2019",
"points": 6100,
"period_end": "12/31/2019"
},
"available_points": 6100,
"redeemed_points": 0,
"awarded_points": 6100,
"pending_points": 0,
"expiration_schedule": [
{
"expiration_date": "18-Jan-2020 11:17:12",
"points": 6100
}],
"has_opted_out": false
},
"success":true
}
This will get the details of the user along with available and redeemed points.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/users/{user_email}
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | Email of the user |
first_name | string | First name of the user |
last_name | string | Last name of the user |
dob | string | Date of birth of user, if available |
address_line1 | string | User address, if available |
address_line2 | string | User address, if available |
city | string | name of city, if available |
state | string | state name, if available |
country | string | country name, if available |
phone_country_code | string | international country code for phone, if available |
phone_number | string | user’s phone number, if available |
zipcode | string | location’s zipcode, if available |
user_id | string | Unique identifier for user passed by merchant |
redeemed_points | integer | Points redeemed by the user |
available_points | integer | Points currently available to the user |
awarded_points | integer | Total number of points that have been awarded to the user |
pending_points | integer | Points pending for approval |
loyalty_tier_id | string | ID of the loyalty tier currently assigned to the user |
loyalty_tier_name | string | Name of the loyalty tier currently assigned to the user |
tier_details | array | Details regarding the period of the tier and points earned during that period |
expiration_schedule | array | Array of expiration schedules |
referral_code | string | Referral code of the user |
referral_url | string | Referral URL of the user |
has_opted_out | boolean | Indicates whether the user has opted out of the loyalty program |
referrer_email | string | Email address of the friend who has referred the current user |
loyalty_enroll_time | string | Date (mm/dd/yyyy) when the user enrolled into the loyalty program |
Get Eligible Activities
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/eligible_activities"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/eligible_activities",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": [
{
"activity_id": "created_an_account",
"rules": {},
"is_activity_available_to_user": true,
"activity_name": "Account Creation",
"activity_type": "fixed",
"activity_description": "Earn points when you create your loyalty account.",
"points_earning_description": "",
"points": 100
},
{
"activity_id": "made_a_purchase",
"rules": {},
"is_activity_available_to_user": true,
"activity_name": "Purchase on website",
"activity_type": "bonus_multiplier",
"activity_description": "Earn points for every dollar you spend in purchases.",
"points_earning_description": "Make a purchase and earn points",
"bonus_multiplier": 1
},
{
"activity_id": "write_a_review",
"rules": {
"frequency": {
"range": "DAY",
"limit": "3",
"actions_completed": 0
}
},
"is_activity_available_to_user": true,
"bonus_multiplier": 1,
"activity_name": "Write a Review",
"activity_description": "Earn points for writing a review.",
"points_earning_description": "Write a review and earn points",
"activity_type": "bonus_multiplier"
}
],
"success": true
}
This will return information about the activities available to the user. User’s email ID will be used to search and return user specific information.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/users/{user_email}/eligible_activities
Response Body
Attribute | Type | Description |
---|---|---|
is_activity_available_to_user | boolean | Is the Activity available to the user to perform (true/false) |
activity_type | string | The activity type of the Activity (fixed/bonus_multiplier) |
bonus_multiplier | float | It is the bonus multiplier applied when the activity is performed. Will be available if the activity_type is bonus_multiplier. |
points | integer | It is the number of points earned when the activity is performed. Will be available if the activity_type is fixed. |
rules | object | Contains details about the activity rules. |
points_earning_description | string | The content shown to the user on clicking the activity card (only for purchase on website, write a review and custom activities) |
Get User Redemptions
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/redemptions?is_still_valid=true&order_by=allowed_redeem_points&count=10&start_index=0&fetch_eligible_redemptions=true"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = json.dumps({
"is_still_valid" : true,
"order_by" : "allowed_redeem_points",
"count" : 10,
"start_index" : 0,
"fetch_eligible_redemptions" : true
})
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/redemptions",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"total": 2,
"redemptions": [
{
"redemption_name": "25% OFF COUPON",
"giftcard_description": "25% Off Coupon for 2100 points",
"redemption_type": "Percentage Discount",
"is_active": false,
"allowed_redeem_points": 2100,
"redemption_value": "25",
"associated_levels": [
"all"
],
"redemption_id": "reward_3063f",
"created_time": "18-May-2017 13:03:05",
"updated_time": "18-May-2017 13:03:05",
"coupon_status": {
"uploaded_coupons": 8,
"remaining_coupons": 6
}
},
{
"redemption_name": "$20 OFF COUPON",
"giftcard_description": "$20 Off Coupon for 1800 points",
"redemption_type": "Fixed Amount Discount",
"is_active": true,
"allowed_redeem_points": 1800,
"redemption_value": "20",
"associated_levels": [
"all"
],
"redemption_id": "reward_eb549",
"created_time": "18-May-2017 13:03:05",
"updated_time": "18-May-2017 13:03:05",
"coupon_status": {
"uploaded_coupons": 25,
"remaining_coupons": 4
}
},
{...}
],
"more": false
},
"success": true
}
This will return information about the redemption options available to the user based on his tier if applicable. User’s email ID will be used to search and return user specific information.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/users/{user_email}/redemptions
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
is_still_valid | boolean | No | Indicates whether only active (true) or all redemptions (false) should be fetched (defaults to true) |
order_by | string | No | The order in which the redemption options will be fetched (defaults to updated_time) |
count | integer | No | The number of redemptions to be fetched (defaults to 12) |
start_index | integer | No | The start index to fetch the data from (defaults to 0) |
fetch_eligible_redemptions | boolean | No | If passed as true, only those redemptions which the user can redeem based on his available points will be fetched (defaults to true) |
Response Body
Attribute | Type | Description |
---|---|---|
total | integer | Total number of redemptions for the user |
redemptions | array | Array of redemptions based on time range, filters and start_index |
more | boolean | Indicates if more number of redemptions are available (true/false) |
Get User Next Tier
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/next_tier"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/next_tier",
headers = headers)
The above command returns JSON structured like this:
{
"data": {
"id": "zrl_platinum",
"name": "Platinum",
"description": "Platinum Tier",
"minimum_points": 5000,
"bonus_multiplier": 1,
"tier_rewards": [
"reward_cb5f8",
"reward_d537f",
"reward_0f28c"
],
"is_active": true,
"is_default": false,
"hide_tier_from_user": false,
"updated_time": "15-Jan-2019 05:06:10",
"created_time": "17-Dec-2018 10:12:34"
},
"success": true
}
This will return information about the next tier available to the user based on his tier if applicable.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/users/{user_email}/next_tier
Response Body
Attribute | Type | Description |
---|---|---|
tier_rewards | array | Reward IDs of the rewards available in the tier |
Unsubscribe User
curl -X POST --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "user_email=bob@zinrelo.com"
"https://api.zinrelo.com/v1/loyalty/unsubscribe_email"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = {
"user_email" : "bob@zinrelo.com"
}
response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/unsubscribe_email",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"user_email": "bob@zinrelo.com",
"status": "unsubscribed"
},
"success": true
}
Unsubscribes a user from the loyalty emails.
HTTP Request
POST https://api.zinrelo.com/v1/loyalty/unsubscribe_email
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
user_email | string | Yes | Email of the user |
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | Email of the user |
status | string | 'Unsubscribed’ status. |
Get All Unsubscribed Users
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/unsubscribed_users?from_date=01/01/2016&to_date=12/31/2016&start_index=0&count=1000"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = json.dumps({
"from_date" : "01/01/2016",
"to_date" : "12/31/2016",
"start_index" : 0,
"count" : 1000
})
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/unsubscribed_users",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"total": 1,
"unsubscribed_emails": [{
"email": "bob@zinrelo.com",
"unsubscribed_on": "10/20/2017"
}],
"more": false
},
"success": true
}
This will get the list of all users who have unsubscribed from loyalty emails
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/unsubscribed_users
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
from_date | string | No | The start date |
to_date | string | No | The end date |
start_index | integer | No | The start index to fetch the data from (defaults to 0) |
count | integer | No | Number of records to fetch (defaults to 1000) |
Response Body
Attribute | Type | Description |
---|---|---|
next_start_index | integer | Next index of record to fetch |
total | integer | Total number of unsubscribed_emails for this merchant |
unsubscribed_emails | array | Array of users based on time range, filters and start_index |
more | boolean | Indicates if more number of users are available (true/false) |
Update User Email
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "old_email_address=bobold@zinrelo.com",
--data "new_email_address=bobnew@zinrelo.com"
"https://app.zinrelo.com/v1/loyalty/update_user_email"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = json.dumps({
"old_email_address" : "bobold@zinrelo.com",
"new_email_address" : "bobnew@zinrelo.com",
})
response = requests.post(url = "https://app.zinrelo.com/v1/loyalty/update_user_email",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": {
"merchant_id": "cad458dc4e",
"old_email_address": "bobold@zinrelo.com",
"new_email_address": "bobnew@zinrelo.com"
},
"success": true
}
This will update user email is Zinrelo with the new email provided
HTTP Request
POST https://app.zinrelo.com/v1/loyalty/update_user_email
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
old_email_address | string | Yes | Old email address of the customer |
new_email_address | string | Yes | New email address of the customer |
Response Body
Attribute | Type | Description |
---|---|---|
merchant_id | string | Partner ID of your account |
old_email_address | string | Old email address of the customer |
new_email_address | string | New email address of the customer |
Block User
curl -X PUT --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://app.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/block"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
response = requests.put(url = "https://app.zinrelo.com/v1/loyalty/users/bob@zinrelo.com/block",
headers = headers)
The above command returns JSON structured like this:
{
"data": {
"last_name": "Baker",
"first_name": "Bob",
"user_email": "bob@zinrelo.com",
"dob": "12/12/1988",
"address_line1": "H1-201,Persian Drive",
"address_line2": "Suite #101",
"city": "Sunnyvale",
"zipcode": "94089",
"state": "CA",
"country": "United States",
"phone_country_code": "+21",
"phone_number": "66656324213",
"referral_code": "BOB1234",
"referral_url": "https://test.zinrelo.com/raf/BOB1234",
"referrer_email": "",
"uid": "user123",
"user_id": "56263eac2d6f2a7715b3d2d1",
"user_status": "blocked",
"loyalty_enroll_time": "01/18/2019",
"loyalty_tier_id": "zrl_platinum",
"loyalty_tier_name": "Platinum",
"tier_details": {
"period_start": "01/01/2019",
"points": 6100,
"period_end": "12/31/2019"
},
"available_points": 6100,
"redeemed_points": 0,
"awarded_points": 6100,
"pending_points": 0,
"expiration_schedule": [
{
"expiration_date": "18-Jan-2020 11:17:12",
"points": 6100
}],
"has_opted_out": false
},
"success":true
}
Blocks the user from the loyalty program.
HTTP Request
PUT https://app.zinrelo.com/v1/loyalty/users/{user_email}/block
Response Body
Attribute | Type | Description |
---|---|---|
user_email | string | Email of the user |
first_name | string | First name of the user |
last_name | string | Last name of the user |
dob | string | Date of birth of user, if available |
address_line1 | string | User address, if available |
address_line2 | string | User address, if available |
city | string | Name of city, if available |
state | string | State name, if available |
country | string | Country name, if available |
phone_country_code | string | International country code for phone, if available |
phone_number | string | User’s phone number, if available |
zipcode | string | Location’s zipcode, if available |
user_id | string | Unique identifier for user passed by merchant |
user _status | string | Current status of the user |
redeemed_points | integer | Points redeemed by the user |
available_points | integer | Points currently available to the user |
awarded_points | integer | Total number of points that have been awarded to the user |
pending_points | integer | Points pending for approval |
loyalty_tier_id | string | ID of the loyalty tier currently assigned to the user |
loyalty_tier_name | string | Name of the loyalty tier currently assigned to the user |
tier_details | array | Details regarding the period of the tier and points earned during that period |
expiration_schedule | array | Array of expiration schedules |
referral_code | string | Referral code of the user |
referral_url | string | Referral URL of the user |
has_opted_out | boolean | Indicates whether the user has opted out of the loyalty program |
referrer_email | string | Email address of the friend who has referred the current user |
loyalty_enroll_time | string | Date (mm/dd/yyyy) when the user enrolled into the loyalty program |
Redemptions
Get Redemptions
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
--data "reward_ids=reward_cb5f8,reward_d537f,reward_0f28c"
"https://api.zinrelo.com/v1/loyalty/redemptions"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
payload = json.dumps({
"redemption_ids" : 'reward_cb5f8,reward_d537f,reward_0f28c'
})
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/redemptions",
headers = headers, data = payload)
The above command returns JSON structured like this:
{
"data": [
{
"redemption_name": "$5 OFF COUPON",
"redemption_id": "reward_cb5f8",
"giftcard_description": "$5 Off Coupon for 500 points",
"is_active": true,
"redemption_type": "Fixed Amount Discount",
"allowed_redeem_points": 500,
"redemption_value": "5",
"created_time": "17-Dec-2018 10:11:42"
},
{
"redemption_name": "$10 OFF COUPON",
"redemption_id": "reward_d537f",
"giftcard_description": "$10 Off Coupon for 1000 points",
"is_active": true,
"redemption_type": "Fixed Amount Discount",
"allowed_redeem_points": 1000,
"redemption_value": "10",
"created_time": "17-Dec-2018 10:11:42"
}
],
"success": true
}
This API will return reward details of the reward ID passed or all the rewards if no ID is passed.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/redemptions
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
redemption_ids | string | No | Redemption IDs separated by comma eg. reward_se23,reward_304f |
Response Body
Attribute | Type | Description |
---|---|---|
allowed_redeem_points | integer | Points required to redeem the redemption. |
redemption_value | string | Monetary value of the redemption |
redemption_type | string | Redemption types can be free shipping,fixed amount discount,percentage discount |
Tiers
Get all Tiers
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/loyalty/tiers"
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
response = requests.get(url = "https://api.zinrelo.com/v1/loyalty/tiers",
headers = headers)
The above command returns JSON structured like this:
{
"data": [
{
"id": "zrl_platinum",
"name": "Platinum",
"description": "Platinum Tier",
"minimum_points": 5000,
"bonus_multiplier": 1,
"tier_rewards": [
"reward_cb5f8",
"reward_d537f",
"reward_0f28c"
],
"rules": {
"2.0x": "Purchase on website, Write a Review"
},
"is_active": true,
"is_default": false,
"hide_tier_from_user": false,
"updated_time": "15-Jan-2019 05:06:10",
"created_time": "17-Dec-2018 10:12:34"
},
{
"id": "zrl_gold",
"name": "Gold",
"description": "1000 points",
"minimum_points": 1000,
"bonus_multiplier": 1,
"tier_rewards": [
"reward_cb5f8",
"reward_d537f",
"reward_0f28c"
],
"rules": {
"1.5x": "Purchase on website, Write a Review"
},
"is_active": true,
"is_default": false,
"hide_tier_from_user": false,
"updated_time": "17-Dec-2018 10:12:37",
"created_time": "17-Dec-2018 10:12:34"
}
],
"success": true
}
This will return information about the next tier available to the user based on his tier if applicable.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/tiers
Query Parameters
Parameter | Type | Mandatory | Description |
---|---|---|---|
tier_ids | string | No | Tier IDs separated by comma eg. silver, gold, platinum |
hide_tier_from_user | boolean | No | Are the tiers being shown to the user or not |
fetch_all | boolean | No | Fetch all the tiers for the program |
Response Body
Attribute | Type | Description |
---|---|---|
tier_rewards | array | Reward IDs of the rewards available in the tier |
rules | map | Promotions/Rules running for the Tier |
Webhooks
Introduction
A Webhook is simply an HTTP callback, an HTTP POST that occurs when something happens. Simply put, it is a simple event-notification via HTTP POST. Webhooks allow you to build or set up integrations, which subscribe to certain events on Zinrelo Loyalty Platform. When one of those events is triggered, we’ll send an HTTP POST payload to the configured URL. Webhooks are aimed at enabling our merchants to extend the functionality provided by the Zinrelo’s Loyalty program by listening to the events and adding additional functionality like CRM integrations, email notifications and integrations with wallets/account credits etc.
Settings
Webhook settings can be configured in the Notifications section of the Zinrelo store.
Sr.No. | Event Name | Description |
---|---|---|
1 | Enable Webhook | Enable/Disable Webhook. |
2 | Webhook URL | Endpoint where events will be posted. |
3 | Events to send Webhook notifications for | Events for which you want to receive notifications for. Currently available events are User Enrollment, Points Awarded, Points Redeemed, Points Deducted |
Webhook processing
For example if your webhook end point is setup at below url: http://example.com/loyalty_webhook/ss_webhook The Webhook post request can be received in the following way:
#Please refer python tab for details
import json
@restrict('POST')
def ss_webhook(self):
try:
body = json.loads(request.body)
#handling code based on the event_type provided
i.e. body.event_type
except Exception as e:
#handle exception
The structure of the webhook post request body is as follows:
{
"id":"570265a77fae7c14c97a2b63",
"data": {..},
"event_type":"evt_points_awarded",
"created":"04-Apr-2016 13:01:27"
}
Receiving a Webhook Notification
Creating a Webhook on your server is simple. Webhook data is sent as JSON in the POST request body. All the details regarding the event are included in the JSON. You are good to go once you parse the JSON.
Responding a webhook
Based on the event type, the payload will contain the user data or the transaction data. In the case of events - User Enrollment the payload contains the user object. Whereas in case of events - Points Awarded, Points Redeemed, Points Deducted the payload will contain the loyalty transaction details.
Your endpoint should return 200 HTTP status code to acknowledge receipt of the event. Any code other than the 200 HTTP status code is considered as a failure, and the event will be fired again with 5 minute intervals until the 200 HTTP status code is received or the maximum number of retry attempts has reached (The default retry attempts limit is 5. Get in touch with your Customer Success Manager to configure the settings).
Best Practices
If your Webhook script performs complex logic, or makes network calls, it is possible that the request would timeout before Zinrelo sees the script’s complete execution. For this reason, you may want to have your Webhook endpoint immediately acknowledge receipt by returning a 200 HTTP status code and then perform the rest of its duties.
Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by logging the events you have processed against the Event ID and then not processing already-logged events
Securities
You may want to confirm that the data received at your Webhook URL is actually the data sent by Zinrelo before acting upon it. To do so, you can use the events API endpoint as described below: Upon receiving a Webhook event follow the below steps:
- Parse the JSON data in request body and get the Event ID value.
- Use the Event ID value to get the data from Zinrelo using the Events API endpoint.
Events API Endpoint
curl -X GET --header "partner-id: cad458dc4e"
--header "api-key: c921e097e6679d21c0cad26a45bfec20"
"https://api.zinrelo.com/v1/events/570265a77fae7c14c97a2b63”
import requests
import json
headers = {'partner-id': 'cad458dc4e',
'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
response = requests.get(
url = "https://api.zinrelo.com/v1/events/570265a77fae7c14c97a2b63",
headers = headers)
The response of the above command is:
{
"data": {
"id": "570265a77fae7c14c97a2b63",
"data": {
"user_last_name": "Pingle",
"activity_id": "became_an_email_subscriber",
"user_first_name": "Aditya",
"user_id": "56263eac2d6f2a7715b3d2d1",
"order_id": null,
"points_status": "approved",
"transaction_type": "award",
"points_expiration_date": null,
"qualified_points": true,
"points": 6,
"points_expired": 0,
"created_time": "04-Apr-2016 13:01:27",
"user_email": "aditya@shopsocially.com",
"activity_name": "Became an Email Subscriber",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "570265a7735f835a2ce12a15",
"approved_time": "04-Apr-2016 13:01:27"
},
"event_type": "evt_points_awarded",
"created": "04-Apr-2016 13:01:27"
},
"success": true
}
This will get the Event data given the Event ID. The ‘data’ returned in the response of the API is identical to the Event data received via Webhook.
HTTP Request
GET https://api.zinrelo.com/v1/loyalty/events/{id}
Response Body
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | Transaction Details\User deatils |
event_type | String | Event Type |
created | String | Event Created Time |
Event Data Format
When configuring a Webhook, you can choose the events you would like to receive payloads for. Subscribing only to the events, which you implement, will help in limiting the HTTP requests to your server.
The events supported by Zinrelo Loyalty program are:
Sr.No. | Event Name | Description |
---|---|---|
1 | User Enrollment | When a new user enrolls into the loyalty program. |
2 | Points Awarded | When points are awarded (approved) to a user. |
3 | Points Redeemed | When a user redeems points. |
4 | Points Deducted | When points are deducted from a user’s loyalty points balance |
5 | Tier Upgrade | When a customer upgrades to a higher tier |
6 | Tier Downgrade | When a customer downgrades to a lower tier |
Example request body for a User Enrollment event:
{"created": "28-Sep-2017 06:49:54",
"data":
{"first_name": "Daena",
"last_name":"Wille",
"user_id": "59cc9b91418a580a512b450d",
"uid": "daen1234",
"dob": "",
"loyalty_tier_id": "zrl_silver",
"available_points": 100,
"loyalty_tier_name": "Silver",
"referral_url": "https://arti55.zinrelo.com/ref/DAE4429",
"referral_code": "DAE4429",
"redeemed_points": 0,
"awarded_points": 100,
"user_email": "Daena1234@shopsocially.com",
"pending_points": 0
},
"id": "59cc9b93418a58027716b78d",
"event_type": "evt_user_enrollment"
}
User Enrollment
User Enrollment event occurs whenever a new user enrolls into Zinrelo loyalty program. On successfull user enrollment we make a call to your webhook URL with following request body:
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | User Details |
event_type | String | Event Type |
created | String | Event Created Time |
Example request body for a Points Awarded event:
{
"id": "57026ce2c22f9f7b50bbdf6e",
"data": {
"activity_id": "became_an_email_subscriber",
"user_first_name": "Aditya",
"order_id": null,
"points_status": "approved",
"points_expired": 0,
"created_time": "04-Apr-2016 13:32:18",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "57026ce2735f835a2ce12a33",
"approved_time": "04-Apr-2016 13:32:18",
"points_expiration_date": null,
"user_id": "56263eac2d6f2a7715b3d2d1",
"transaction_type": "award",
"user_last_name": "Pingle",
"points": 300,
"qualified_points": true,
"activity_name": "Became an Email Subscriber",
"user_email": "aditya@shopsocially.com"
},
"event_type": "evt_points_awarded",
"created": "04-Apr-2016 13:32:18"
}
Points Awarded
Points Awarded event occurs whenever any user has been awarded loyalty points. In the case of the activities where moderation is required, the event occurs once the points have been approved. On successfull points award event, we make a call to your webhook URL with following request body:
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | Transaction Details |
event_type | String | Event Type |
created | String | Event Created Time |
Example request body for a Points Redeemed event:
{
"id": "570265487fae7c14c77a2b63",
"data": {
"points_status": "redeemed",
"user_id": "56263eac2d6f2a7715b3d2d1",
"redemption_name": "new_redemption 50",
"user_first_name": "Aditya",
"transaction_type": "redeem",
"user_last_name": "Pingle",
"coupon_code": "5",
"points": 1,
"redemption_id": "new_redemption_50",
"created_time": "04-Apr-2016 12:59:52",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "57026548735f835a2d16b01c",
"user_email": "aditya@shopsocially.com"
},
"event_type": "evt_points_redeemed",
"created": "04-Apr-2016 12:59:52"
}
Points Redeemed
Points Redeemed event occurs whenever a user redeems his loyalty points. On successfull points redeemed event, we make a call to your webhook URL with following request body:
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | Transaction Details |
event_type | String | Event Type |
created | String | Event Created Time |
Example request body for a Points Deducted event:
{
"id": "57026857c22f9f7b50bbdf6c",
"data": {
"user_first_name": "Aditya",
"user_id": "56263eac2d6f2a7715b3d2d1",
"points_status": "deducted",
"transaction_type": "deduct",
"user_last_name": "Pingle",
"reason": "testing",
"points": 30000,
"points_deducted": 0,
"created_time": "04-Apr-2016 13:12:55",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "57026857735f835a2ce12a27",
"user_email": "aditya@shopsocially.com"
},
"event_type": "evt_points_deducted",
"created": "04-Apr-2016 13:12:55"
}
Points Deducted
Points Deducted event occurs whenever points are deducted from a user’s loyalty points balance. The points can be deducted from Zinrelo store or using API calls. On successful points deduct event, we make a call to your webhook URL with following request body:
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | Transaction Details |
event_type | String | Event Type |
created | String | Event Created Time |
Example request body for a Tier Upgrade event:
{
"id": "57026857c22f9f7b50bbdf6c",
"data": {
"first_name": "Bob",
"last_name": "Baker",
"loyalty_tier_name": "Pearl",
"uid": "76183",
"user_id": "5982d90663fda91f6fb37564",
"dob": "",
"loyalty_tier_id": "zrl_pearl",
"available_points": 1738,
"referral_url": "https://storeforpreviewdahsboard.zinrelo.com/ref/BOB7091",
"referral_code": "BOB7091",
"redeemed_points": 0,
"awarded_points": 1738,
"user_email": "bob@xyz.com",
"pending_points": 0
},
"event_type": "evt_level_upgrade",
"created": "01-Apr-2016 12:26:08"
}
Tier Upgrade
The Tier upgrade event occurs whenever a customer earns enough points to move up to a higher tier. The tier upgrade is processed immediately and the webhook is triggered at the time of upgrade. On successful tier upgrade event, we make a call to your webhook URL with following request body:
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | Transaction Details |
event_type | String | Event Type |
created | String | Event Created Time |
Example request body for a Tier Downgrade event:
{
"id": "57026857c22f9f7b50bbdf6c",
"data": {
"first_name": "Bob",
"last_name": "Baker",
"loyalty_tier_name": "Pearl",
"uid": "76183",
"user_id": "5982d90663fda91f6fb37564",
"dob": "",
"loyalty_tier_id": "zrl_pearl",
"available_points": 1738,
"referral_url": "https://storeforpreviewdahsboard.zinrelo.com/ref/BOB7091",
"referral_code": "BOB7091",
"redeemed_points": 0,
"awarded_points": 1738,
"user_email": "bob@xyz.com",
"pending_points": 0
},
"event_type": "evt_level_degrade",
"created": "01-Apr-2016 12:26:08"
}
Tier Downgrade
The Tier downgrade event occurs whenever enough points are deducted from a customer’s account resulting in downgrading to a lower tier. The tier downgrade is processed immediately and the webhook is triggered at the time of downgrade. On successful tier downgrade event, we make a call to your webhook URL with following request body:
Parameter | Type | Description |
---|---|---|
id | String | Event ID |
data | Dictionary | Transaction Details |
event_type | String | Event Type |
created | String | Event Created Time |
JavaScript API
Get User Info
This javascript function will get the details of the user from Zinrelo Platform.
zrl_mi.get_loyalty_user_info()
window.zrlmi_loyalty_user_info_success_handler = function(data){
console.log(data)
/***code to handle success response***/
}
window.zrlmi_loyalty_user_info_failure_handler = function(data){
console.log(data)
/***code to handle failure response***/
}
Request
zrl_mi.get_loyalty_user_info()
The above command returns JSON structured like this:
{"available_points":19862,
"awarded_points":20200,
"dob":"07/22/1990",
"first_name":"RT",
"last_name":"406",
"loyalty_tier_id":"zrl_level_platinum",
"loyalty_tier_name":"Platinum",
"pending_points":0,
"redeemed_points":338,
"referral_code":"ART7993",
"referrer_email":"",
"ss_uid":"b986ff5cdf5eb5498ec492a9939b6628",
"success":true,
"uid":"arti 406",
"user_email":"arti@shopsocially.com"}
Response Body
Parameter | Type | Description |
---|---|---|
awarded_points | Integer | Total Points awarded to the user |
dob | String | Date of birth of the user |
first_name | String | First name of the user |
last_name | String | Last name of the user |
loyalty_tier_id | String | ID of loyalty tier currently assigned to user |
loyalty_tier_name | String | Name of loyalty tier currently assigned to user |
pending_points | Integer | Points pending for approval |
redeemed_points | Integer | Points redeemed by the user |
referral_code | String | Current user’s referral code |
referrer_email | String | Referrer’s email address If the current user is referred by someone |
ss_uid | String | Zinrelo internal user ID |
uid | String | Unique ID of user at merchant side |
user_email | String | Email of the user |
Status Codes
Our API returns standard HTTP success or failure status codes. For failures, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP and API status codes we might return are listed below.
HTTP Status codes
Code | Title | Description |
---|---|---|
200 | OK | The request was successful. |
400 | Bad Request | Bad request. |
401 | Unauthorized | Your API key is invalid. |
404 | Not Found | The resource does not exist. |
50X | Internal Server Error | An error occured with our API. |
API Status Codes
Code | Description |
---|---|
601 | One or more request parameters do not have values in the expected format |
602 | User does not exist |
603 | Redeemption operation failed |
604 | Invalid Redemption ID |
605 | Inactive Redemption ID |
606 | Redemption coupon expired |
607 | Insufficient redeemable points |
608 | Redemption coupons exhausted |
609 | Duplicate Order ID |
610 | Activity is in paused state |
611 | Invalid Activity ID |
612 | end_date cannot be less than start_date |
613 | Invalid Order ID |
614 | Points to deduct is greater than points available to deduct for the Order ID |
615 | missing parameters |
616 | Invalid event ID |
617 | Maximum award limit exceeded |
618 | Points could not be awarded because exclusion rule was applied |
619 | Multiple accounts found |
620 | Invalid Product ID |
621 | Maximum product quantity exceeded |
622 | User record has been deleted |
623 | User has been blocked |