Upload methods
API integration (real-time)
Connect your system directly to Loyalife’s Transaction API to submit events as they occur. The Rule Engine evaluates and awards points immediately after each submission. When to use API integration:- Your program requires near-instant point updates after a purchase
- Members expect to see their balance update right after a transaction
- Your platform already has API capabilities
Batch processing (file upload)
Data accumulates over a defined period and is processed in bulk at scheduled intervals. Files are transferred via SFTP to the Loyalife server. When to use batch processing:- Your source system already exports transaction logs on a schedule (end of day, hourly, etc.)
- Near-real-time updates are not required by your program
- You are migrating a large historical transaction dataset
SFTP file upload
1
Obtain SFTP credentials
Request your program-specific SFTP credentials from your Loyalife administrator. These credentials are unique per program.
2
Connect via VPN
SFTP access is VPN-restricted. Connect to your approved VPN before attempting the SFTP connection.
3
Upload to the correct directory
Connect to the SFTP server and upload your file to the appropriate directory based on file type:
4
Monitor processing
Processing begins automatically after upload. Check the Logs report in Reports & Analytics for upload status, processed record count, and any rejected rows.
File types and formats
Loyalife supports four file types for batch data ingestion. All files are CSV or pipe-delimited depending on program configuration.TXN — transaction file
The TXN file submits purchase or activity transactions for points evaluation by the Rule Engine. The columns included in a TXN file are fully customisable — whatever fields the client’s source system can export are defined as global attributes or custom attributes in Loyalife, and those values are ingested and stored against each transaction.CPD — customer profile data file
The CPD file updates member profile information — used when member data is managed in an external system and synced to Loyalife in bulk. The fields included are customisable per program: any member attributes the client wants to maintain in Loyalife are defined as global or custom attributes, and the CPD file carries those values in on each sync.BNS — bonus file
The BNS file credits bonus points outside of the standard transaction-to-rule evaluation flow. It is used for manual bonus awards, promotional grants, or migration of historical balances. Like other file types, the columns are configurable and map to the attributes defined for your program.BNS entries bypass the Rule Engine — points are credited directly without evaluating IF/THEN conditions. Use BNS for direct awards only; use TXN files when you want the Rule Engine to calculate the correct point amount from a transaction.BNS file uploads post as Credit By Bonus entries on the member’s ledger. If the BNS file is used for a balance migration or inbound transfer from an external programme, the entries may alternatively appear as Credit Transfer. Both are filterable in Transactional reports under Reports & Analytics → Transaction Category.
CRD — card reference data file
The CRD file links cards and supplementary accounts to a primary member. It is used in banking programs where a single member account has multiple cards — for example, a primary cardholder with one or more supplementary cards for family members.CRD is relevant for programs where transactions arrive tagged with a card identifier rather than the primary member’s Relation Reference. Loyalife uses the CRD mapping to resolve the correct member account when evaluating rules and posting points. Without a CRD entry, transactions submitted with an unrecognised card identifier are rejected.
Pre-processing layer
For programs that receive data files from external systems (banks, ERP platforms, payment networks), Loyalife’s pre-processing layer transforms files before ingestion. Pre-processing runs between SFTP upload and Rule Engine evaluation. Any fields a client wants to share — across any file type — are defined as global attributes or custom attributes in Loyalife. The pre-processing layer normalises the incoming file so those fields are correctly structured and can be pushed into Loyalife, where they are stored against the matching member or transaction attribute. This means the client’s source file does not need to match Loyalife’s internal format exactly — the pre-processing configuration handles the mapping. Typical transformations applied during pre-processing include date format normalisation, column merging, header stripping, and field trimming. The specific transformations are configured per program during onboarding based on the client’s source file structure.Multi-program routing (BIN-based)
For programs receiving a single file containing records for multiple loyalty programs (common in banking / card programs), the pre-processing layer can route records to the correct program using a BIN (Bank Identification Number) or equivalent routing key. Each routing key maps to exactly one program. Records with an unrecognised routing key are written to a reject file rather than ingested into any program.File validation
Validation happens at two levels: the file as a whole, and then each row individually.File-level validation
These checks run before any rows are processed. A failure here rejects the entire file:Row-level validation
Each row is validated independently. A failed row is rejected and logged; all other valid rows continue processing:
Rejected rows do not prevent other valid rows from processing. The rejection count and per-row error messages appear in the Logs report.
Complete error reference
File-level errors (entire file rejected):
Row-level errors (individual row rejected):
Processing errors (file fails during backend processing):
Rule evaluation on batch files
After validation, each accepted row is evaluated against all active rule groups, following the same logic as real-time API transactions:- Member’s segment membership is checked against each rule group’s linked segment
- IF conditions are evaluated against the transaction’s attributes
- Matching rules apply their THEN reward
- Points are posted to the member’s account
- Tier re-evaluation is triggered for the member
Error file delivery (SFTP return)
After processing, Loyalife can automatically deliver the error file (rows that failed validation) back to the client’s SFTP server. This enables fully automated pipelines where the client system receives rejected rows without accessing the Loyalife UI. This feature is configured per program and supports selective file types (e.g., only CPD and TXN error files, not BNS). Error files are placed in the client’s designated inbound SFTP path. The file naming convention mirrors the input file with a suffix indicating it is a rejection report.Error file delivery to client SFTP is enabled by the Loyalife operations team during program setup. It is not available as a self-service toggle in the admin UI.
Monitoring uploads
Go to Reports & Analytics → Data Exports → Logs to see:
Click any upload entry to see per-row rejection details, including the exact error message for each rejected row.
Troubleshooting
File uploaded but no points were awarded.- Check the Logs report for the file’s processing status.
- Review the rejection count — if all rows were rejected, look at the error messages.
- Verify Relation References in the file match enrolled members in Loyalife.
- Confirm active rule groups exist for the members and transaction types in the file.
- Confirm you are connected to the approved VPN.
- Verify credentials are correct and have not expired.
- Contact your Loyalife administrator to check SFTP server status.
- Verify the file was uploaded to the correct directory for its type (
upload/TXN,upload/CPD,upload/BNS,upload/CRD). - Check file encoding — Loyalife expects UTF-8 encoded files.
- Ensure the first row is the header row and that column names match the configured template exactly.
- Loyalife can send email notifications when a CPD, TXN, or BNS file finishes processing. The Super Admin is always notified. Additional email addresses can be added under Program Settings → Notifications. Contact your Loyalife administrator to configure this.