Tips and Tricks

File encoding, formatting rules, common pitfalls, and tips for large-scale imports in Open Loyalty.

Follow these guidelines to avoid the most common import issues. Most import errors are caused by file encoding, empty fields, or incorrect data formats — all of which are easy to prevent.

🛠️ File preparation

Use UTF-8 encoding with Unix line endings

All import files must use UTF-8 encoding and Unix (LF) line endings.

Windows-style line endings (CRLF — \r\n) can break server-side file type detection, causing the system to reject your file with an "invalid file type" error — even when the content is perfectly valid.

How to check and fix line endings:

• VS Code — click the CRLF indicator in the bottom status bar and select LF, then save

• Notepad++ — go to Edit → EOL Conversion → Unix (LF)

• Command line (Mac/Linux) — sed -i 's/\r$//' yourfile.json

This issue is especially common with files exported from Excel, generated on Windows, or copy-pasted from email.

Remove unused fields — don't leave them empty

Open Loyalty validates file structure strictly. If a field is present in the file, it must contain valid data. Empty elements cause "This form should not contain extra fields" errors.

✅ Correct

member-correct.xml

<customer>
  <email>[e-mail]</email>
  <firstName>Jane</firstName>
  <lastName>Doe</lastName>
</customer>

Only the fields you actually need are included.

❌ Incorrect

member-incorrect.xml

<customer>
  <email>[e-mail]</email>
  <firstName>Jane</firstName>
  <lastName>Doe</lastName>
  <company>
    <name></name>
    <nip></nip>
  </company>
  <address>
    <address1></address1>
    <city></city>
    <country></country>
  </address>
</customer>

Empty <company> and <address> blocks will trigger validation errors.

Use ISO country codes

The country field in member imports requires ISO 3166-1 alpha-2 codes (two-letter codes). Numeric codes or full country names are not accepted.

✅ Correct	❌ Incorrect
US	840, United States
GB	826, United Kingdom
PL	616, Poland

Include timezone offsets in timestamps

For transaction imports, always include the timezone offset in date fields (e.g., 2024-06-15T10:30:00+02:00). Without it, timestamps may be interpreted incorrectly, causing campaigns not to trigger or points to be calculated for the wrong period.

Validate before uploading

Before uploading, validate your file:

• XML — use an online XML validator or your code editor's built-in validation

• JSON — use jsonlint.com or your editor's JSON formatting

• CSV — open in a text editor (not Excel) to verify the header row and delimiters

🧩 Tips for large migrations

For databases with 100,000+ records:

• Test first — run a test migration with a small dataset (100–500 records) to catch formatting issues early

• Split files into batches of 5,000–10,000 records to avoid timeouts

• Allocate separate days for each import type to avoid overloading the system

• Stagger uploads — wait for one batch to finish processing before uploading the next

• Notify Open Loyalty support beforehand at so the team can ensure proper resource allocation

🛠️ Debugging failed imports

When the Admin Panel shows a generic error message, the API response often contains more detail:

1. Open your browser's Developer Tools (F12)

2. Go to the Network tab

3. Retry the import

4. Click the failed request and inspect the Response payload

The response body typically includes the specific field and validation rule that caused the failure.

Common error reference

Error message	Cause	Solution
Invalid file type / MIME type error	Windows CRLF line endings	Convert to Unix LF line endings
This form should not contain extra fields	Empty XML elements or unexpected JSON keys	Remove all unused fields from the file
Country validation error	Numeric or text country codes	Use ISO 3166-1 alpha-2 codes (e.g., US, PL)
Invalid JSON/XML	BOM character, encoding issues, or invisible characters	Save as UTF-8 without BOM, remove invisible characters
Segment import succeeds but members don't appear	Target segment is condition-based, not static	Create a static segment and import into that
Timeout on large import	File too large	Split into batches with a file max 100 MB

👉 For sample files and field references for each import type, see Sample import files.