Introduction
Batch Mode Integration is a convenient way to award points for offline custom activities such as entering a store, running 10K etc. Please familiarize yourself with Batch Mode Integration before proceeding with this article.
To award points for any offline custom activity other than a purchase, you must upload the following custom file to the designated FTP Server in CSV format.
This file is described in detail below.
Custom Offline Activity File (required)
This file contains details about each custom offline activity, other than purchases, for which points are to be awarded. If points are to be awarded for multiple custom activities, all such activities should be combined into this single file before uploading.
However, we highly recommend using separate files for each custom activity.
Please Note: If you intend to upload a single file for multiple custom activities, ensure to include the respective custom attributes linked to each activity."
Thus, this file may contain multiple activity IDs. A prerequisite is that a custom activity corresponding to each activity ID has been configured and made live in the TrueLoyal console. The activity ID will be used to associate the award transaction with an activity. Points will be awarded based on the rules configured in the TrueLoyal Admin Console.
The naming convention for this file is ZN_ACTIVITY_YYYYMMDD.csv. For example, a file with orders for April 27, 2017 should be named ZN_ACTIVITY_20170426.csv.
📘
Please Note:
The csv file name should not contain any special characters.
CSV Fields
The fields contained in this CSV file are described in the table below:
| Field | Description | Mandatory (Yes/ No)? |
|---|---|---|
| activity_timestamp | Date in YYYYMMDD format followed by time in HH:MM:SS format (24 hours) on which the order was placed. For example: 20231116/19:50:02 | Yes |
| points_expiration_date | Pass the date and time for point expiration. This will override the global settings of point expiration. Format: YYYYMMDD/HH:MM:SS (20241221/18:00:04). Passing the time is optional. | No |
| user_email | Email address of the member. | Yes (If member_id is passed in CSV, user_email address becomes optional.) |
| user_name | Name of the member (first name and the last name) | Yes |
| member_id | Unique Identifier (Member ID) for the member object in the client’s system. | Yes (if this column is passed in CSV) |
| client_user_id | User ID assigned to the member by the admin. If no value was assigned any random value can be passed. | Yes |
| user_phone | The phone number of the buyer without country code. | No |
| activity_id | The unique activity ID stored with Zinrelo. You can find this in the Zinrelo admin console under the activity name. The ID has to match the Zinrelo record exactly or the points will not be awarded. | Yes |
| points_awarded | Number of points to be awarded to the user for this activity. | Yes |
| activity_description | Description of the activity which was performed. Example: Visited the store. | No |
| approval_date | Date and time on which the transaction will be auto approved. Format: YYYYMMDD/HH:MM:SS (20231221/18:00:04) | No |
| activity_url | If you provide the URL, then the activity_description will be hyperlinked to the activity_url. So, it will show a link where or how the activity was performed. | No |
| {activity_id}.{client_internal_id} or {activity_id}@{client_internal_id} |
This is activity specific custom attributes. To know more, click here. You can pass in custom attributes that you want Zinrelo to associate with the transaction. The types of attributes you can create:
|
No |
| {global}.{client_internal_id} or {global}@{client_internal_id} |
This is global attributes or activities global attributes. To know more, click here.
|
No |
📘
Please Note:
If your program does not utilize an email address as the primary identifier, the 'member_id' field will be included in the CSV. Otherwise, it will not appear in the CSV file.
If you do not have any data for the optional columns, don't pass the column name.
Error messages
Here are all the error messages that you may received:
| Error Message | Description |
| "Invalid numerical value" | The value provided is not a valid numerical value for the specified data type in custom attributes. |
| "Incorrect date format. Expected - YYYYMMDD/H:M:S or YYYYMMDD" | The provided date format is incorrect. It should adhere to either YYYYMMDD/H:M:S or YYYYMMDD. |
| "Invalid list value provided" | An invalid value has been passed in a list data type created for custom attributes. |
| "Order ID is mandatory for Purchase transaction." | The Order ID is essential for identifying transactions uniquely, particularly for purchase transactions. |
| "One of the rows related to this order is invalid" | This message indicates that a row related to the order contains incorrect data. |
| "Unable to determine if the row is Purchase or Return" | This message is displayed when crucial columns such as order_type, order_total, order_subtotal, product_price, and quantity are empty, making it impossible to identify the transaction type. |
| "Member ID is mandatory" | The Member ID field is required when provided in CSV. |
| "User Email is mandatory" | This field is obligatory for clients using the V1 store. |
| "Order Subtotal has to be positive." | The order subtotal must have a positive value; negative values are not accepted. |
| "Product price has to be of type float" | Product price should be of type float/ integer; other data types are not accepted. |
| "Product quantity has to be of type int" | Product quantity should be an integer; incorrect data types are not permitted. |
| "Order Subtotal has to be greater than Zero." | For purchase transactions, the subtotal or total must be greater than zero. This error occurs when these values are zero or when product prices and quantities multiply to zero. |
| "User not registered in Zinrelo" | This message appears when a user is not found in the Zinrelo database, particularly when auto-enrollment is disabled and only added to purchase orders. |
| "Error occured while creating user in Zinrelo" | This error message indicates backend errors during user creation in Zinrelo. |
| "Unable to register user in Zinrelo as member_id is absent" | For V2 customers, the member_id field is mandatory, and this error occurs when it's not provided. |
| "Unable to register user in Zinrelo as email/client_user_id are absent" | For V1 customers, the email field is mandatory, and this error occurs when email or user_id is not provided. |
| "Unable to calculate return amount" | Calculation of the return amount failed due to incorrect provided data. |
| "return_subtotal": "return amount should not be 0" | The return amount should not be zero. |
| "return_subtotal": "return amount should be passed" | To calculate return amount- product prices or quantity should be provided. If not then subtotal or total should be specified. |
| "return_subtotal": "return amount greater than available amount" | The return amount exceeds the available points. |
| "order_id": "no transaction present for order_id:{order_id}" | The provided order ID does not correspond to any transaction. |
| "quantity": "Product quantity exceeded" | The provided product quantity exceed or incorrect. |
| "returned_product_id": "returned product id is invalid" | The provided product ID for the returned product is invalid. |
| "user_deleted": "Returned transaction belongs to the deleted user." | The returned transaction details belong to a deleted user. |
| "user_blocked": "Returned transaction belongs to the blocked user." | The returned transaction details belong to a blocked user. |
| "not_enough_points_to_deduct": "User does not have enough points to deduct" | Insufficient points to deduct for return transaction. |
| "email_not_passed": " User email not passed or User email passed is incorrect or Client User ID is incorrect" | Email or user_id is mandatory for V1 store customers during return transactions. |
| "user_not_exists": "No user found for the given email/member_id." | Unable to identify the user as provided email address or member_id is incorrect. |
| "Unexpected error occured. Exception: {error}" | A generic exception occurred during daily transactions. |
| "Error in reading custom activity information from {file_name} for merchant {merchant_key} : {error}" | A generic exception occurred while reading custom attributes from a specified file. |
| missing parameters | This message indicates missing mandatory parameters. For more details, refer to this document. |
Note:
- The CSV file should not exceed 5000 records. If you wish to upload a larger volume, please create a new CSV file with the additional records.
- Please ensure that you review the "numeric data" before adding it to any field. There is a possibility that it could be converted to a scientific data format when inserted into the CSV file.
- The downloaded CSV will contain only activity attributes as it specifically pertains to activities. Reward and reward global attributes will not be included.
- The CSV file must not have any rows that solely consist of white spaces.
- When uploading a CSV file through FTP, it undergoes processing every 8 hours. However, for manual processing, the file is processed immediately.
- You can process a maximum of 50 files per day.
- CSV files should not contain double quotes.
- When a custom activity is paused, it won't appear for download in the dropdown menu. Additionally, if a custom activity is paused, TrueLoyal won't award points for that particular activity.
- The file must be encoded in UTF-8 format and saved as a CSV file.
📘
Note:
Our system records all date and time fields in UTC time. This applies to the system generated fields such as enrollment date as well as the date time fields passed through the batch files.
Download Sample CSV
To download the sample CSV file, go to General >> Settings >> Batch Mode within the TrueLoyal admin console.
Choose 'Custom Activity File' as the file type and select the desired custom activity type. Then, click on 'Download'."
Comments
Please sign in to leave a comment.