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:
| Parameters | Description | Possible Values |
|---|---|---|
| member_id | This 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_id | This 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_date | This 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_passed | This 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_attributes | This 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_date | This 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:
To calculate points for an order, priority is given to the product prices. If product prices are not present, the order subtotal will be used to award points. If there is a discount applied on the order, the product prices should also reflect the discount i.e. the discounted product prices should be sent in the API instead of the full price.
The sum of product prices should match the order subtotal - the amount on which points are expected to be awarded.
Some systems have limitations in sending the discounted prices of products. To handle such situations, we compare the order subtotal with the sum of product prices. In the event that the order subtotal is lesser, we assume that the order discount doesn't reflect in the product prices. So we prorate the product prices and then use those prorated prices for awarding points.
The attributes for made_a_puchase activity are detailed below:
| Attribute | Mandatory | Type | Description |
|---|---|---|---|
| order_total | Yes | integer | Total order value. |
| order_subtotal | Yes | integer | Order value without shipping and taxes. |
| order_id | Yes | string | 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. |
| coupons | No | string | Coupon code used. You can provide a single coupon code using the following format: "coupons": "$5OFFVYZ". Alternatively, you can pass multiple coupon codes with a space, like this: "coupons": "$5OFFVYZ,$10FFEDT,$05RTNVLW". |
| tags | No | string | List 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. |
| reason | No | string | Reason for awarding the points to the member. |
| product_id | Yes | string | Unique product identifier. |
| product_quantity | Yes | integer | Quantity bought. |
| product_category | No | list | Internal Product Category |
| product_price | Yes | integer | Price of the product |
| product_title | Yes | string | Title of the product |
| product_image_url | No | string | url 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.
- When individual product prices are provided, the subtotal is ignored.
- In instances where product information is absent, the purchase amount is derived from the 'order_subtotal' field.
submit_a_receipt activity
Mandatory attribute is 'receipt_files'. 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":[""],
}
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":[""],
}
Please enter the code after "base64,".
Updated 4 months ago