Custom Activity Integration via Batch Mode
With this article, learn how to award points for offline purchases.
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 Zinrelo 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 Zinrelo 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} | 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: - String - Date - List - Numerical The expected value for date formal: MM/DD/YYYY HH:MM:SS (passing the time is optional). | No |
| {global}.{client_internal_id} | This is global attributes or activities global 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: - String - Date - List - Numerical The expected value for date formal: MM/DD/YYYY HH:MM:SS (passing the time is optional). | 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.
You can find the error message here.
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, Zinrelo 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 Zinrelo admin console.
Choose 'Custom Activity File' as the file type and select the desired custom activity type. Then, click on 'Download'."
Updated 7 months ago