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 TrueLoyal. This enables TrueLoyal 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.trueloyal.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 TrueLoyal account is created. These can be found in your TrueLoyal 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 TrueLoyal'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": "johndoe@gmail.com",
       "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 TrueLoyal.

{
  "data": {
          "user_email": "johndoe@gmail.com",
          "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

TrueLoyal 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 TrueLoyal Admin Console.

Error Handling

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

Standard HTTP status codes:

TrueLoyal API Status Codes: