Setting up Purchase Tracking

Introduction

The fundamental function of a loyalty rewards program is to drive additional purchases. Therefore purchase tracking is a very important part of the API.

The Purchase Tracking API passes the data for each purchase to Zinrelo. This enables Zinrelo to award points for purchases. This API is typically called from the server side after the checkout process is complete. The API call can be triggered when the order is created, shipped or completed depending on the business requirements.

Purchase API

The API call is a HTTP POST request to this end point URL.

POST https://help.zinrelo.com/reference/award-points

Click here for detailed documentation.

API Authentication

All API calls have to be authenticated with your API key and partner ID. The API key and partner ID are automatically generated for you when your Zinrelo account is created. These can be found in your Zinrelo admin console under the General >> Settings section.

For authenticating an API call, you have to send your Partner ID, and an API Key in the HTTP header of each API request.

Send the keys in the HTTP header of each API request as given below:

'api-key': '<your-api-key'
'partner-id' : '<your-partner-id>'

Calling the Purchase API

Here is a sample Python script to call Zinrelo's Purchase API when the user checkout process is complete and the order has been registered. Note that if there are multiple products, then they need to be populated in the products[ ] object.

import requests
import json

headers = {'partner-id': 'cad458dc4e', 
           'api-key': 'c921e097e6679d21c0cad26a45bfec20'}
products = [{"category": "Medicines",
            "img_url": "https://cdn.website.com/product1/img.jpg",
            "price": "26.95",
            "product_id": "1234df",
            "quantity": "1",
            "tags": "medicines,capsules",
            "title": "Stress Free Emotions",
            "url": "http://www.website.com/product1.html"}] 

payload = {"user_email": "[email protected]",
       "total=32.17", 
       "subtotal=26.95", 
       "order_id=75a2726d13artibb10",
       "currency=USD",
       "coupon_code=CODE101",
       "products"=json.dumps(products)}

response = requests.post(url = "https://api.zinrelo.com/v1/loyalty/purchase",
                        headers = headers, data = payload)

📘

Please Note: The order subtotal should be calculated as the sum of the subtotals of all products in the order, without taking into account any discounts. The discounted price needs to be adjusted in products and passed accordingly.

For more information, please refer to the Award API help document.

Here is a description of the various product parameters used to create the products[ ] object in the code snippet above. There will be one entry for each product item in this order.

JSON Response

Here is the sample JSON structured response that you will receive from Zinrelo.

{
  "data": {
          "user_email": "[email protected]",
          "last_name": "John",
          "first_name": "Doe",
          "activity_id": "made_a_purchase",
          "activity_name": "Made a Purchase",
          "transaction_type":"award",
          "points": 270,
          "points_status": "auto_approved",
          "created_time": "30-Mar-16 19:20:22"
  },
  "success":true
}

Expected Result

Zinrelo will respond with standard HTTP success or failure codes. In case of a success response, the points will reflect in the user's account in the Zinrelo Admin Console.

Error Handling

For failures, Zinrelo will also include extra information about what went wrong, encoded in the response as JSON. The various HTTP and API status codes Zinrelo might return are listed below.

Standard HTTP status codes:

Zinrelo API Status Codes: