Appearance
Import Validation
Validation is the first stage of a data import. You upload your CSV files and TiruPay checks every row against the rules of your service - without changing any data. The result is a structured report telling you exactly what is correct, what must be fixed before importing, and what would be skipped.
You can validate as often as you need. Nothing is written until the separate import stage runs.
Preparing Your Files
One File per Entity Type
Export your data as CSV, with one file per entity type - for example customers.csv, subscriptions.csv, orders.csv. You can and should upload several files in a single validation so that references between them resolve against each other.
Required Columns
Every entity type has a set of required and optional columns, listed in the Field Reference. Two columns matter for every file:
external_id- the unique ID this record had in your source system. Required on every row.- Any reference column (ending in
_external_id) that links the row to another record.
Column Names Are Flexible
You do not have to rename your columns to match TiruPay exactly. TiruPay recognises a wide range of common names in both English and German. For example, a customer's first name is recognised from first_name, firstname, vorname, given_name, and more.
If a column name is close to a known one but not exact, TiruPay still maps it and tells you it did so, so you can confirm it guessed correctly. If it cannot map a column at all, that column is reported as unrecognised and you can correct it (see Correcting column mappings).
File Format
- Encoding: UTF-8 (with or without BOM) and Latin-1 are both accepted.
- Delimiter: comma by default. If your export uses a different delimiter, state it when validating.
- Header row: the first row must contain the column names.
- Size: up to 25 MB per file, and up to 50 MB across all files in one validation.
Large Migrations: Split Into Several Runs
The 50 MB total limit is per validation run, not per migration. A large migration is done as a sequence of runs, importing the data in batches. This is safe by design: because every row carries an External ID, data you have already imported is recognised in later runs and skipped rather than duplicated. You can also split a single large entity - for example half your customers in one run, the other half in the next.
The one rule to follow is order by dependency: a row whose reference points at a record that is neither in the same upload nor already imported is skipped (see References and skipped rows). So import records before the records that depend on them.
A dependency-safe order is:
- Configuration & people:
customer,user,feature,balance_type,balance_usage_category,coupon - Per-customer records:
mandate,credit_balance,balance,subscription,feature_assignment - Activity & history:
order,order_position,payment,order_refund,applied_coupon,subscription_extension,subscription_pending_change,credit_transaction,balance_usage,balance_usage_item,order_feature_log
Within one run you can still upload several files together - keep records and the records they reference in the same run where convenient (for example customers and their subscriptions), and the references resolve against each other directly.
Re-running is always safe
Re-validating or re-importing the same file never creates duplicates. Rows that match a record already in your service are reported as collisions and skipped, leaving the existing record untouched. If in doubt, split smaller and run more often.
Running a Validation
Validation is an admin action against the service you are importing into.
POST /admin/import/validateYou provide:
| Parameter | Description |
|---|---|
service_id | The service you are importing into. |
files | One or more CSV files. |
entity_types | (optional) The entity type per file, when auto-detection is not reliable (see below). |
header_corrections | (optional) Column mapping corrections (see below). |
mapping_template_id | (optional) A saved mapping template to apply (see Mapping Templates). |
delimiter | (optional) The column separator. Defaults to ,. Use ; for semicolon files. |
The response is a validation report.
Stating the Entity Type Explicitly
TiruPay auto-detects each file's entity type from its name and columns. When a file name is ambiguous - for example balance_usage_categories.csv, which looks similar to balance_usage - state the type explicitly with entity_types, a JSON object mapping each file name to its entity type:
json
{
"balance_types.csv": "balance_type",
"balance_usage_categories.csv": "balance_usage_category"
}You only need to list the files whose type you want to fix; others are still auto-detected. A file name that is not part of the upload, or an unknown entity type, is rejected with a clear error rather than being silently ignored.
Correcting Column Mappings
When the report lists columns under unrecognized_headers, or maps a column to the wrong field, you tell TiruPay the correct mapping and re-validate.
header_corrections maps, per file, each CSV column name to the TiruPay field it should fill:
json
{
"kunden.csv": {
"kundennr": "external_id",
"mailto": "email",
"rufname": "first_name"
}
}After re-validating with corrections, those columns are mapped exactly as you specified, and their contents are then validated like any other column. Map a column to an empty string ("notizen": "") to leave it out of the import.
Looking Up Field Names
To build corrections or templates programmatically, fetch the valid targets:
GET /admin/import/entity-types?service_id=...It returns every entity type with its fields. Each field has a name (the value to use in header_corrections and template mappings), whether it is required, the aliases recognised automatically, its field_type, and - for reference columns - the entity type it references. The same information is listed in the Field Reference. Each entity type also has an is_catalog flag, marking the types whose records you can review and tag before an import (see Linking to existing catalog items).
Mapping a column reveals its content errors
A column that was unrecognised is not validated for content - TiruPay does not yet know what it holds. Once you map it (for example to email), the values in that column are checked too. So it is normal to see new content errors appear after a correction - that is the validator now able to inspect data it previously could not.
Mapping Templates
Validating a real export usually takes several rounds of correcting columns before everything is recognised. A template lets you save that work for a source system you import from repeatedly - so you do not redo it on every upload.
A template stores, per file pattern, both the entity type and the column mapping for matching files. That means a template captures everything that would otherwise be entered by hand each time: the entity_types and the header_corrections.
| Action | Endpoint |
|---|---|
| List templates | GET /admin/import/mapping-templates?service_id=... |
| Create a template | POST /admin/import/mapping-templates |
| Update a template | PUT /admin/import/mapping-templates/{id} |
| Delete a template | DELETE /admin/import/mapping-templates/{id} |
Template Structure
A template has a name and a list of file rules. Each rule targets files by a glob pattern and may carry an entity type, a column mapping, or both:
json
{
"service_id": "your-service-id",
"name": "Legacy CRM export",
"file_rules": [
{
"pattern": "customer_*.csv",
"entity_type": "customer",
"mappings": {
"kundennr": "external_id",
"mailto": "email",
"rufname": "first_name"
}
},
{
"pattern": "orders.csv",
"entity_type": "order",
"mappings": { "best_nr": "order_number" }
}
]
}pattern(required) - a glob matched against the uploaded file name.*matches any run of characters and?matches a single one.customer_*.csvmatchescustomer_1.csv,customer_2.csv, and so on.entity_type(optional) - the entity type for matching files.mappings(optional) - a{column: field}mapping for matching files.
This is ideal when an export is split across many files: one customer_*.csv rule covers every customer file at once.
Which Rule Applies
If several rules match the same file, the most specific one wins: a rule with fewer wildcards beats one with more, and an exact pattern (no wildcards) always wins. So you can have a broad customer_*.csv rule and still override a single customer_vip.csv file with its own rule - the order of rules does not matter.
Applying a Template
When validating, pass mapping_template_id to apply the template to your upload. The template fills in entity types and column mappings for every matching file automatically.
You can still pass entity_types and header_corrections at the same time: inline parameters take precedence over the template. Inline corrections override on a per-column basis (the template's other columns for that file still apply), so you can adjust a one-off file without changing the saved template.
Linking to Existing Catalog Items
You can import your product catalog (article categories, articles, extensions and PAYG plans) directly - see Product Catalog. If instead your catalog already exists in TiruPay (for example, set up by hand), tag each existing catalog item with the External ID it had in your source system so that imported subscriptions and order positions can link to it:
PATCH /admin/import/external-id/article/{article_id}
PATCH /admin/import/external-id/article_extension/{extension_id}with a body of:
json
{ "external_id": "ALT-ART-1" }Once tagged, any imported row that references ALT-ART-1 resolves to that catalog item. Until then, rows referencing it are reported as skippable (see References and skipped rows).
This same endpoint can set or clear the External ID on any importable record - useful if you need to re-link or correct a record after import. Send null or an empty string to clear it.
External IDs must be unique per type
For catalog records (article categories, articles, article extensions, features, balance types, PAYG plans, coupon categories and coupons), two records of the same type in one service cannot share an External ID - otherwise an imported reference would be ambiguous. Setting a duplicate is rejected with 409 Conflict.
Reviewing Assigned External IDs
To check which External IDs are set, read them back:
GET /admin/import/external-id/{entity_type}/{entity_id} # one record
GET /admin/import/external-id/{entity_type}?service_id=... # all tagged records of a typeThe single-record form returns the External ID currently set on that record (or null if none). The list form returns every record of that type in the service that carries an External ID - for example, all articles you have tagged so far. Both reads are restricted to the services you manage, just like setting the ID.
For the catalog types listed above, each list entry also carries a label (the record's name), and include_untagged=true returns the records without an External ID as well - the quickest way to find what still needs tagging before an import:
GET /admin/import/external-id/article?service_id=...&include_untagged=trueThe Validation Report
The report summarises the whole validation and breaks it down per entity type.
Top-Level Result
| Field | Meaning |
|---|---|
can_proceed_to_import | true only when there are no blocking errors. This is the single signal for whether you may move on to the import stage. |
header_mapping_complete | false when at least one required column could not be mapped in some file. |
entities | One result block per entity type (see below). |
collisions | Rows that duplicate a record already in your service (see Collisions). |
summary | Aggregate counts across all files. |
The summary contains:
| Count | Meaning |
|---|---|
total_rows | All data rows across all files. |
error_rows | Rows with at least one blocking error. |
warning_rows | Rows with at least one warning. |
skippable_rows | Rows that are valid but would be skipped because a reference could not be resolved. |
collision_rows | Rows that duplicate an existing record. |
Per-Entity Result
Each entry in entities describes one entity type:
| Field | Meaning |
|---|---|
entity_type | The detected or stated entity type. |
source_file | The file(s) the rows came from. |
total_rows / valid_rows / skippable_rows | Row counts for this entity type. |
header_mappings | How each CSV column was mapped, with a confidence score. |
unrecognized_headers | Columns that could not be mapped and need a correction. |
issues | The individual findings (see Severities). |
Each issue identifies the affected row_index (0-based; -1 means the issue applies to the whole file, such as a missing required column), the field it concerns, a stable code, a human-readable message, and a severity.
Severities
Every issue has one of three severities. They determine whether you can proceed.
| Severity | Blocks import? | Meaning |
|---|---|---|
| error | Yes | The row cannot be imported as-is. Fix it and re-validate. |
| warning | No | Informational. The row will import, but you should confirm the noted behaviour. |
| unresolved | No | The row is valid, but a reference it depends on was not found. The row will be skipped at import. |
can_proceed_to_import is true as long as there are no error issues. Warnings and unresolved references do not block the import - but unresolved rows will simply not be imported, so review skippable_rows carefully before proceeding.
References and Skipped Rows
When a row points at another record - a subscription pointing at a customer, an order position pointing at an order - TiruPay checks that the target exists, either in the same upload or already in your service.
If the target is not found, the row gets an unresolved issue and will be skipped at import. This is deliberately not a hard error: the missing record might simply be in a file you have not uploaded yet, or a catalog item you have not yet tagged.
To resolve these:
- Include the referenced records in the same validation (upload the customer file together with the subscription file), or
- Make sure the referenced records were imported in an earlier run, or
- For catalog items, tag them with their External ID (see Linking to existing catalog items).
Collisions (Duplicates)
TiruPay also checks whether a row would duplicate a record that already exists in your service - for example a customer with an email address that is already in use, or an order with an existing order number. Such rows appear under collisions.
Collisions never block the import. The duplicate row is skipped, leaving the existing record untouched. This makes it safe to re-run an import: rows that were already imported are recognised as duplicates and skipped rather than created twice.
Understanding Errors
The validator produces stable code values so you can recognise and handle each kind of issue. They fall into a few groups.
Missing or Empty Required Data
| Code | Meaning & fix |
|---|---|
missing_required_columns | A required column is missing from the file entirely. Add the column, or map an existing one to it with a correction. |
required_field_missing | A required field is empty in this row. Fill in a value. |
name_required | A non-company customer has neither a first nor a last name. Provide at least one. |
company_name_required | A customer marked as a company is missing the company name. Provide it, or unset the company flag. |
Wrong Format or Type
| Code | Meaning & fix |
|---|---|
invalid_email | The value is not a valid email address. Correct it. |
invalid_int | A whole-number field contains something that is not an integer. |
invalid_decimal | A numeric field contains a non-number. Both 12.50 and 12,50 are accepted. |
invalid_bool | A true/false field has an unrecognised value. Use true/false (also yes/no, ja/nein, 1/0). |
invalid_datetime | A date field could not be parsed. Use 2024-01-15 or 2024-01-15T10:00:00; 15.01.2024 is also accepted. |
invalid_country_code | A country must be a 2-letter ISO code, e.g. DE. |
invalid_currency | A currency_code must be a 3-letter ISO code, e.g. EUR. |
invalid_enum_value | The value is not one of the allowed options for this field. The message lists the valid values. |
Automatic value mapping
For fields with a fixed set of options (such as a status or interval), TiruPay accepts common English and German wordings and near-misses. When it maps a value automatically - for example monatlich to a monthly interval, or correcting an obvious typo - it raises the warning enum_value_auto_mapped so you can confirm the mapping is what you intended. This is a warning, not an error: the row will import.
Inconsistent Combinations
These errors occur when individual fields are valid on their own but contradict each other.
| Code | Meaning & fix |
|---|---|
ambiguous_order_position | An order line references both an article and an article extension. Reference exactly one. |
missing_order_position_target | An order line references neither an article nor an extension. Reference exactly one. |
discount_percentage_required | A percentage coupon has no percentage value. |
discount_percentage_out_of_range | A coupon percentage is outside 0-100. |
discount_percentage_not_allowed | A fixed-amount coupon also carries a percentage. Remove it. |
discount_amount_required | A fixed-amount coupon has no amount value. |
discount_amount_negative | A coupon amount is negative. |
discount_amount_not_allowed | A percentage coupon also carries a fixed amount. Remove it. |
currency_required | A fixed-amount coupon needs a currency_code. |
refund_amount_mismatch | A refund's gross amount does not equal net + tax. Correct the amounts. |
cancelled_at_required | A subscription marked cancelled has no cancellation date. |
amount_not_positive | A transaction amount must be greater than zero. |
balance_negative | A balance value cannot be negative. |
balance_math_mismatch | A transaction's resulting balance does not match the amount and the balance before it. |
limit_payg_negative | A pay-as-you-go limit cannot be negative. |
cost_negative / units_used_negative / quantity_negative | These values cannot be negative. |
Dependent on a Referenced Record
These checks compare a row against the record it references.
| Code | Severity | Meaning & fix |
|---|---|---|
unresolved_ref | unresolved | A referenced record could not be found in the upload or your service. The row will be skipped. See References and skipped rows. |
article_not_found | unresolved | A subscription references an article that is not in your catalog or not yet tagged with its External ID. The row will be skipped. See Linking to existing catalog items. |
article_not_subscription | error | A subscription references an article that exists but is not a subscription article. Point it at a subscription article. |
limit_payg_not_allowed_for_prepaid | error | A pay-as-you-go limit was set on a balance whose type is prepaid. Remove the limit, or use a pay-as-you-go balance type. |
price_per_unit_required | error | A usage category of a prepaid balance type needs a price per unit. |
price_per_unit_not_allowed_for_payg | error | A usage category of a pay-as-you-go balance type must not have a price per unit; those prices are configured separately. |
price_per_unit_negative | error | A price per unit cannot be negative. |
grace_days_ignored_for_prepaid | warning | A grace-period value was set on a prepaid balance type, where it has no effect. It will be ignored. |
Runtime Readiness
These checks look beyond the row itself to the links TiruPay relies on once the data is live. A missing link is reported now - at validation - rather than surfacing weeks later as a failed job or a paused subscription. A link counts as present if the partner record is in the same upload or already in your service.
| Code | Severity | Meaning & fix |
|---|---|---|
missing_completed_order | error | An active subscription has no completed order. Renewals and upgrades fail without one - include a completed order for the subscription (in this upload or a previous one). |
balance_usage_without_items | error | A usage event has no items. It cannot be created without at least one item - include the items referencing it. |
payg_activation_missing | error | A pay-as-you-go balance has no active activation. Usage on it would fail until an activation exists. (Checked for balances already in your service.) |
article_not_available_in_country | error | The subscription's article is not available for sale in its tax country: its country_code, otherwise the paying customer's country (the customer's own unless someone else pays). Renewal would fail - configure the article's availability for that country in the catalog before importing. |
tax_category_missing | error | No tax category exists for the order's tax country: its country_code, otherwise the paying customer's country. Orders cannot be taxed without one - add a tax category for the country before importing. |
order_country_not_found / subscription_country_not_found | error | An order's or subscription's country_code does not match any known country. Use a country that already exists, or leave it empty to use the paying customer's country. |
mandate_not_of_paying_customer | error | The subscription's mandate belongs to a different customer than the one who pays. Renewals would charge the wrong customer - reference a mandate of the paying customer. |
payg_paid_by_others | error | An order or subscription paid by someone else contains an article or extension with pay-as-you-go usage. Usage is always billed to the customer who owns the balance - remove paying_customer_external_id or the pay-as-you-go item. |
subscription_currency_not_found / order_currency_not_found / credit_balance_currency_not_found / coupon_currency_not_found | error | A row's currency_code does not match any known currency. Use a currency that already exists (e.g. EUR, CHF, GBP, USD, AUD, CAD, JPY), or have it added first. |
subscription_mandate_missing | warning | An active subscription has no payment mandate (neither a mandate_external_id nor payment_method_identifier + payment_partner). It will pause at the next renewal until a mandate is imported - import mandates for these subscriptions. |
order_without_positions | warning | An order has no positions, so its total is zero. Import the order's positions to make it complete. |
order_total_mismatch | warning | An order's total_amount does not match the sum of its imported positions. Verify the figures. |
balance_amount_inconsistent | warning | A balance's current_balance is inconsistent with its co-imported usage history. Verify the figures. |
customer_without_credit_balance | warning | A customer has no Credit Balance (prepaid wallet) in this upload or your service. An empty one will be created automatically at import time - verify the opening balance afterwards. |
credit_balance_currency_mismatch | warning | A credit_balance row specifies a currency_code that does not match the customer's country currency. This balance will not be used as the default billing wallet and is almost certainly a data error. |
requires_group_missing | warning | An entity type is being imported without a required companion. For example, balance_usage cannot be fully created without at least one balance_usage_item. The companion records may already exist in your service, in which case this warning can be ignored. |
File-Level
| Code | Meaning & fix |
|---|---|
unknown_entity_type | TiruPay could not determine what kind of data the file holds. State it with entity_types. |
A Typical Correction Cycle
- Upload your files and read the report.
- Resolve
unrecognized_headerswithheader_corrections(or save a template). - Fix rows with error issues, working through the
issueslist byrow_index. - Review unresolved rows: upload the missing referenced files, or tag the missing catalog items.
- Re-validate. Repeat until
can_proceed_to_importistrue. - Review remaining warnings, skippable rows, and collisions - these will not block the import but tell you what will be skipped or auto-mapped.
- Proceed to the import stage.
Next Steps
- Import Execution - what happens when you run the import, automatic side effects, and the audit log.
- Field Reference - every importable entity type, its columns, and the column names TiruPay recognises.
- Data Import overview - concepts and the end-to-end workflow.