Setting up Purchase Tracking

Set up the purchase tracking server side API to award points for purchases.

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.

api authentication

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.

ParameterTypeMandatoryDescription
member_idstringYesUnique Identifier (Member ID) for the member object in the client’s system which was used while creating a member in Zinrelo.
activity_idstringYesUnique ID that identifies an activity in Zinrelo. This is the activity against which the transaction has to be recorded.
approval_datestringNoDate and time on which the transaction will be auto approved.
transaction_attributesjsonYesEvery activity has two predefined transaction attributes - reason and tags. While creating a transaction, data can be passed in these attributes. Custom attributes: In addition to the predefined attributes, you can create custom attributes for an activity and pass data in those attributes when the transaction is created. The purchase activity is a special case where there are additional predefined transaction attributes and some of them are mandatory, such as- product_id, price, quantity, product title and url.

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:

CodeTitleDescription
200OkThe request was successful.
400Bad RequestBad request.
401UnauthorizedYour API key is invalid.
404Not FoundThe resource does not exist.
500Internal Server ErrorAn error occurred with our API.
503Service UnavailableService Unavailable.

Zinrelo API Status Codes:

Status CodeError CodeMessage
200UNABLE_TO_UPLOAD_PHOTOUnable to upload the photo. Please try again later.
400ATTRIBUTE_NOT_UNIQUEIdParams name passed is not a unique attribute.
200MEMBER_ID_ALREADY_IN_USEMember ID already in use.
200INVALID_MEMBER_STATUSInvalid member status.
200MEMBER_BLOCKEDMember has been blocked.
200MAX_AWARDS_EXCEEDEDMaximum award limit exceeded.
200INVALID_AMOUNT_TO_DEDUCTNot enough points to deduct.
400INVALID_JSONInvalid JSON format.
400INVALID_REQUESTInvalid request: unsupported Content-Type [content-type].
200INCORRECT_MEMBER_ID_PASSEDIncorrect Member ID passed.
200STORE_INACTIVEStore is not active.
200MEMBER_DELETEDMember record has been deleted.
200EXCLUDED_TRANSACTIONPoints could not be awarded because exclusion rule was applied.
404TRANSACTION_DOES_NOT_EXISTTransaction does not exist.
500INTERNAL_SERVER_ERRORInternal server error.
400INVALID_REQUEST_PARAMETER_VALUESInvalid request parameter value.
200INVALID_PHOTOInvalid file type or file size. Please make sure uploaded file type is JPG, JPEG, or PNG. and file size should be less than 10MB.
200PAUSED_ACTIVITYActivity is in paused state.
400ID_PARAM_NAME_NOT_FOUNDIdParams name passed does not exist.
401ERROR_UNAUTHORIZEDSome error occurred while authenticating your account at Zinrelo. Please verify your API credentials.
200DUPLICATE_ORDER_IDLoyalty Points already awarded for the Order ID.
200MEMBER_CREATION_UNSUCCESSFULMember creation unsuccessful.
400MERCHANT_DOES_NOT_EXISTMerchant does not exist.
200TRANSACTION_ATTRIBUTE_NOT_UNIQUEUnique transaction attribute for given activity is not unique.
200INVALID_MEMBERMember does not exist.
400INVALID_CURSORInvalid start cursor provided
503SERVICE_UNAVAILABLEAPI Service is unavailable. Please contact Zinrelo support.
200INACTIVE_REWARDThis reward is inactive and cannot be redeemed.
200AUTO_REDEEMABLE_REWARDCannot redeem auto redeemable reward via API.
200INVALID_REWARD_FOR_USERReturned product quantity exceeds order quantity.
200MAX_REWARDS_EXCEEDEDMaximum redemption threshold for reward reached.
200INSUFFICIENT_REDEEMABLE_POINTSUser points balance insufficient.
200INVALID_REWARD_FOR_TIERThis reward is not valid for user tier.
200ORDER_NOT_EXISTOrder with this id does not exist.
200PRODUCT_QUANTITY_EXCEEDEDReturned product quantity exceeds order quantity.
200INVALID_PRODUCT_IDIncorrect product id passed.
200RETURN_VALUE_EXCEEDS_AVAILABLE_BALANCEReturned order value exceeds user's points balance.
200PRODUCT_ID_AND_RETURN_AMOUNT_PASSEDPlease pass either returned product id or returned amount.