Award API Parameters

Introduction

The Award API is specifically designed to award points to members for various activities. This document aims to provide you with a comprehensive understanding of the API, including its parameters and the range of possible values associated with them.

Request Parameters

Here is a brief description of the Award API request parameters:

ParametersDescriptionPossible Values
member_idThis parameter represents a unique identifier for the member object in the client's system, which was used when creating the member in Zinrelo.It can be an email address, phone number, or member ID.
activity_idThis parameter is a unique ID that identifies a specific activity in Zinrelo. It is used to specify the activity against which the transaction needs to be recorded.created_an_account/ made_a_purchase/ write_a_review, etc.
transaction_dateThis parameter represents the date and time of the transaction's occurrence. The format for the transaction date should be in the format <MM/DD/YYYY HH:MM:SS> Our APIs records all date and time fields in UTC time. Note: The transaction date is considered for all activities except for the "submit a receipt" activity.10/05/2019 23:10:55
points_passedThis parameter allows you to set custom points for an activity, overriding the default points set in the admin console. Note: It is applicable to all activities except for the "made_a_purchase" activity.100
transaction_attributesThis parameter represents custom attributes associated with the transaction. You can also pass activity attributes in this parameter. These attributes provide additional information about the transaction, enabling more detailed tracking, analysis, and awarding of points.
Please find details about this parameter below.
tags/ reason/ order_id/ coupons, etc.
approval_dateThis parameter is to pass the date and time on which the transaction will be auto approved. Format: <MM/DD/YYYY HH:MM:SS> Our APIs records all date and time fields in UTC time.10/15/2019 16:10:50

Transaction Attributes

Let's understand how transaction attributes are passed for activities.

Every activity has two predefined transaction attributes - reason and tags. While awarding points for an activity, data can be passed in these attributes.

Custom attributes: In addition to the predefined attributes, you can define custom attributes for each activity and pass data in those attributes.

Note: "transaction_attributes" is mandatory only for 3 of the predefined activities.

made_a_purchase activity

Mandatory attributes are order_id, order_total, order_subtotal.

The order_subtotal should be greater than 0.01

A sample structure of the transaction_attributes for the made_a_purchase activity is given below:

{
"tags" : ["tag1","tag2"],
"reason" : "purchase",
"order_id" : "75",
"coupons" : "$5OFFVYZ,$10FFEDT,$05RTNVLW",
"order_total" : "1000",
"order_subtotal" : "1000",

"products" : [{
"product_id": "112",
"product_quantity": "1",
"product_category": "tshirt", "blue range", "on sale",
"product_price": "15",
"product_title": "Sweatshirt",
"product_image_url": ""
},

{
"product_id": "980",
"product_quantity": "2",
"product_category": "sales", "straight range of pants", "formals", "on 10% discount",
"product_price": "10.017",
"product_title": "Pant",
"product_image_url": ""
}]

}

📘

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.

The attributes for made_a_puchase activity are detailed below:

AttributeMandatoryTypeDescription
order_totalYesintegerTotal order value.
order_subtotalYesintegerOrder value without shipping and taxes.
order_idYesstringWhen 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.
couponsNostringCoupon code used. You can provide a single coupon code using the following format: "coupons": "$5OFFVYZ". Alternatively, you can pass multiple coupon codes as a comma-separated string, like this: "coupons": "$5OFFVYZ, $10FFEDT, $05RTNVLW".
tagsNostringList of tags can be passed as "tags": ["tag1", "tag2"]. This format enables you to assign multiple tags to the transaction, each tag separated by a comma.

Additionally, you also have the option to pass a single value in the tags field. For example, you can use the format "tags": "purchasemade" to assign a single tag to the transaction.
reasonNostringReason for awarding the points to the member.
product_idYesstringUnique product identifier.
product_quantityYesintegerQuantity bought.
product_categoryNolistInternal Product Category
product_priceYesintegerPrice of the product
product_titleYesstringTitle of the product
product_image_urlNostringurl of the product image

Note: The attributes like “product_id”, “product_price”, “product_quantity” and “product_title” are mandatory only when you pass product attributes.

submit_a_receipt activity

Mandatory attribute is 'receipt_files'. 'receipt_uid' is the optional field. Expected data is a list of images/pdfs encoded in base64 format. To convert an image to base64 format, click here.

A sample structure of the transaction_attributes for the submit_a_receipt activity is given below:

{

"receipt_files":[""],"receipt_uid":[""]

}

Note: The response will show "receipt_uid" in the "additional_data" field.

upload_photo activity

Mandatory attribute is image_file. Expected data is a list of images/pdfs encoded in base64 format. To convert an image to base64 format, click here.

A sample structure of the transaction_attributes for the upload_photo activity is given below:

{

"image_file":[""]

}