Introduction to Batch Mode Integration

This article will help you understand how the batch mode integration works.

Introduction

Batch Mode Processing is a convenient way to integrate purchase/ return/ custom activities that are performed offline, for example, an in-store purchase via Point-of-Sale (POS) system. All loyalty activity files in the designated CSV format can be uploaded in a specified format to an FTP server setup for you.

Batch Mode Integration flow chart

All loyalty activities are passed through a business rules engine to apply the rules relevant to that activity. For example, if 5X points are to be awarded for every dollar of purchase, the 5X business rule will be applied to each purchase imported from the batch upload. This information is sent to the Loyalty Rewards engine which processes the points. Loyalty members are notified by email after the uploaded file is processed.

FTP Location

The FTP location and the access credentials to upload your files can be found in the ‘General’ tab of your admin console.

Automated Processing

Alternatively, you can also upload a .CSV file in the console itself. Before processing the file a validation check will run at our end and we'll let you know the status of the file. If it has some errors, you will be notified about the same and also in case it is processed successfully.

You can upload the Daily Transaction file, Custom Activity file, Product file, return, and purchase files through FTP.

Please Note: Files uploaded from the Admin console will be processed immediately.

📘

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.

Batch Mode Upload

You can upload only two types of file via Batch Mode:

  1. Custom Activity File
  2. Daily Transactions
manual processing

Custom Activity File

Awarding points for any offline custom activity other than purchase can be done by grouping all such activities into a common file in CSV format.

This file contains details about each custom offline activity, other than purchases, for which points are to be awarded. This file will contain 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. File Naming Convention: ZN_ACTIVITY_YYYYMMDD.csv.

For details about this file, visit page Custom Activity Integration via Batch Mode.

The fields contained in this CSV file are described in the table below:

FieldDescriptionMandatory (Yes/ No)?
activity_timestampDate 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
user_emailEmail address of the member.Yes (If member_id is passed in CSV, user_email address becomes optional.)
user_nameName of the member (first name and the last name)Yes
member_idUnique Identifier (Member ID) for the member object in the client’s system.Yes (if this column is passed in CSV)
client_user_idUser ID assigned to the member by the admin. If no value was assigned any random value can be passed.Yes
user_phoneThe phone number of the buyer without country code.No
activity_idThe 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_awardedNumber of points to be awarded to the user for this activity.Yes
activity_descriptionDescription of the activity which was performed. Example: Visited the store.No
approval_dateDate and time on which the transaction will be auto approved. Format: YYYYMMDD HH:MM:SS (20231221/18:00:04)No
activity_urlIf 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

Daily Transactions File

To award points for any offline purchase/return activity, you must upload the Purchase/ Return Activity file in CSV format.

This file contains a list of all purchase transactions and/or return transactions with the order details necessary to award points for purchases or deduct points for returns. File Naming Convention: ZN_DAILY_TRANSACTIONS_YYYYMMDD.csv.

The fields contained in this CSV file are described in the table below:

FieldDescriptionMandatory (Yes/ No)?Example
order_timestampDate in YYYYMMDD format followed by time in HH:MM:SS format (24 hours) on which the order was placed.Yes20200721/ 00:00:00
timezoneThe timezone in which the purchases were made. This field is case-sensitive. The value should always be in all caps. NoPST, CST, IST, etc.
order_idThe order ID of the order which is being placed. This field is used to uniquely identify the order.YesFX-250123-110-12431
order_typeThis field tells whether this row is a purchase or return. The value of this field can be "purchase" or "return."Yes (If no value is provided in the column, it will be interpreted as a 'purchase.' Therefore, it is essential to provide a value, particularly when the order type is 'return.)purchase/ return
order_totalGross total amount of the order including shipping. discount, etc.Yes
Note: If it is not passed, the system will rely on order_subtotal.
53.49
order_subtotalNet total amount of the order excluding shipping, discount. Points will be awarded to the member based on this amount. Should be greater than 0.Yes
Note: If it is not passed, the system will rely on product price and quantity.
39.99
coupon_codeValue of the coupon_code used while making this purchase.No15OFF
currencyThree letter currency code of the order placed.NoUSD
user_nameName of the member (first name and the last name)YesJohn Doe
member_idUnique Identifier (Member ID) for the member object in the client’s systemYes (if this column is passed in CSV)Customer ID/ GUID/ Email Address/ or Phone Number
user_emailEmail address of the member.Yes (If member_id is passed in CSV, user_email address becomes optional.)[email protected]
client_user_idUser ID assigned to the member by the admin. If no value was assigned any random value can be passed.YesJOH08976
approval_dateDate and time on which the transaction will be auto approved. Format: YYYYMMDD HH:MM:SS.No20231221/18:00:04
user_phoneThe phone number of the buyer without country code.No9713332246
product_idThe product ID of the product purchased.No333215
product_pricePrice of the product. Value should be a Float (default 0.0)No (If the fields "order_total" and "order_subtotal" are not passed, this field becomes mandatory.)39.99
quantityQuantity of the ordered product. Value should be a Int (default1)No (If the fields "order_total" and "order_subtotal" are not passed, this field becomes mandatory.)1
product_titleName of the ordered product.NoFuji Instax Camera
product_categoryCategory to which ordered product belongs. Multiple categories can be passed in comma separated format without space.Nopromotion,camera
product_tagTags which describe the product. Multiple tags can be passed in comma separated format without space.Nosale item,clearance
{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 uses an email address as the primary identifier, the email address value should be updated in both the Member ID and the email address columns.

For details about these files, visit page Daily Transactions Integration via Batch Mode.

📘

Please Note:

  1. 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.
  2. 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.
  3. The downloaded CSV will contain only activity attributes as it specifically pertains to activities. Reward and reward global attributes will not be included.
  4. The CSV file must not have any rows that solely consist of white spaces.
  5. When uploading a CSV file through FTP, it undergoes processing every 8 hours. However, for manual processing, the file is processed immediately.
  6. You can process a maximum of 50 files per day.
  7. CSV files should not contain double quotes.
  8. 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.
  9. The file must be encoded in UTF-8 format and saved as a CSV file.