> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/main-features/imports-exports/imports/tips-and-tricks.md).
# Tips and Tricks
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.
{% hint style="warning" %}
**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`
{% endhint %}
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.
{% tabs %}
{% tab title="✅ Correct" %}
{% code title="member-correct.xml" %}
```xml
jane@example.com
Jane
Doe
```
{% endcode %}
Only the fields you actually need are included.
{% endtab %}
{% tab title="❌ Incorrect" %}
{% code title="member-incorrect.xml" %}
```xml
jane@example.com
Jane
Doe
```
{% endcode %}
Empty `` and `` blocks will trigger validation errors.
{% endtab %}
{% endtabs %}
#### 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](https://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
{% hint style="warning" %}
**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
{% endhint %}
### 🛠️ 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://help.openloyalty.io/main-features/imports-exports/imports/tips-and-tricks.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.