Skip to content

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:

  1. Configuration & people: customer, user, feature, balance_type, balance_usage_category, coupon
  2. Per-customer records: mandate, credit_balance, balance, subscription, feature_assignment
  3. 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/validate

You provide:

ParameterDescription
service_idThe service you are importing into.
filesOne 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.

ActionEndpoint
List templatesGET /admin/import/mapping-templates?service_id=...
Create a templatePOST /admin/import/mapping-templates
Update a templatePUT /admin/import/mapping-templates/{id}
Delete a templateDELETE /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_*.csv matches customer_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 type

The 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=true

The Validation Report ​

The report summarises the whole validation and breaks it down per entity type.

Top-Level Result ​

FieldMeaning
can_proceed_to_importtrue only when there are no blocking errors. This is the single signal for whether you may move on to the import stage.
header_mapping_completefalse when at least one required column could not be mapped in some file.
entitiesOne result block per entity type (see below).
collisionsRows that duplicate a record already in your service (see Collisions).
summaryAggregate counts across all files.

The summary contains:

CountMeaning
total_rowsAll data rows across all files.
error_rowsRows with at least one blocking error.
warning_rowsRows with at least one warning.
skippable_rowsRows that are valid but would be skipped because a reference could not be resolved.
collision_rowsRows that duplicate an existing record.

Per-Entity Result ​

Each entry in entities describes one entity type:

FieldMeaning
entity_typeThe detected or stated entity type.
source_fileThe file(s) the rows came from.
total_rows / valid_rows / skippable_rowsRow counts for this entity type.
header_mappingsHow each CSV column was mapped, with a confidence score.
unrecognized_headersColumns that could not be mapped and need a correction.
issuesThe 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.

SeverityBlocks import?Meaning
errorYesThe row cannot be imported as-is. Fix it and re-validate.
warningNoInformational. The row will import, but you should confirm the noted behaviour.
unresolvedNoThe 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 ​

CodeMeaning & fix
missing_required_columnsA required column is missing from the file entirely. Add the column, or map an existing one to it with a correction.
required_field_missingA required field is empty in this row. Fill in a value.
name_requiredA non-company customer has neither a first nor a last name. Provide at least one.
company_name_requiredA customer marked as a company is missing the company name. Provide it, or unset the company flag.

Wrong Format or Type ​

CodeMeaning & fix
invalid_emailThe value is not a valid email address. Correct it.
invalid_intA whole-number field contains something that is not an integer.
invalid_decimalA numeric field contains a non-number. Both 12.50 and 12,50 are accepted.
invalid_boolA true/false field has an unrecognised value. Use true/false (also yes/no, ja/nein, 1/0).
invalid_datetimeA date field could not be parsed. Use 2024-01-15 or 2024-01-15T10:00:00; 15.01.2024 is also accepted.
invalid_country_codeA country must be a 2-letter ISO code, e.g. DE.
invalid_currencyA currency_code must be a 3-letter ISO code, e.g. EUR.
invalid_enum_valueThe 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.

CodeMeaning & fix
ambiguous_order_positionAn order line references both an article and an article extension. Reference exactly one.
missing_order_position_targetAn order line references neither an article nor an extension. Reference exactly one.
discount_percentage_requiredA percentage coupon has no percentage value.
discount_percentage_out_of_rangeA coupon percentage is outside 0-100.
discount_percentage_not_allowedA fixed-amount coupon also carries a percentage. Remove it.
discount_amount_requiredA fixed-amount coupon has no amount value.
discount_amount_negativeA coupon amount is negative.
discount_amount_not_allowedA percentage coupon also carries a fixed amount. Remove it.
currency_requiredA fixed-amount coupon needs a currency_code.
refund_amount_mismatchA refund's gross amount does not equal net + tax. Correct the amounts.
cancelled_at_requiredA subscription marked cancelled has no cancellation date.
amount_not_positiveA transaction amount must be greater than zero.
balance_negativeA balance value cannot be negative.
balance_math_mismatchA transaction's resulting balance does not match the amount and the balance before it.
limit_payg_negativeA pay-as-you-go limit cannot be negative.
cost_negative / units_used_negative / quantity_negativeThese values cannot be negative.

Dependent on a Referenced Record ​

These checks compare a row against the record it references.

CodeSeverityMeaning & fix
unresolved_refunresolvedA referenced record could not be found in the upload or your service. The row will be skipped. See References and skipped rows.
article_not_foundunresolvedA 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_subscriptionerrorA subscription references an article that exists but is not a subscription article. Point it at a subscription article.
limit_payg_not_allowed_for_prepaiderrorA 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_requirederrorA usage category of a prepaid balance type needs a price per unit.
price_per_unit_not_allowed_for_paygerrorA 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_negativeerrorA price per unit cannot be negative.
grace_days_ignored_for_prepaidwarningA 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.

CodeSeverityMeaning & fix
missing_completed_ordererrorAn 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_itemserrorA usage event has no items. It cannot be created without at least one item - include the items referencing it.
payg_activation_missingerrorA 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_countryerrorThe 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_missingerrorNo 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_founderrorAn 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_customererrorThe 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_otherserrorAn 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_founderrorA 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_missingwarningAn 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_positionswarningAn order has no positions, so its total is zero. Import the order's positions to make it complete.
order_total_mismatchwarningAn order's total_amount does not match the sum of its imported positions. Verify the figures.
balance_amount_inconsistentwarningA balance's current_balance is inconsistent with its co-imported usage history. Verify the figures.
customer_without_credit_balancewarningA 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_mismatchwarningA 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_missingwarningAn 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 ​

CodeMeaning & fix
unknown_entity_typeTiruPay could not determine what kind of data the file holds. State it with entity_types.

A Typical Correction Cycle ​

  1. Upload your files and read the report.
  2. Resolve unrecognized_headers with header_corrections (or save a template).
  3. Fix rows with error issues, working through the issues list by row_index.
  4. Review unresolved rows: upload the missing referenced files, or tag the missing catalog items.
  5. Re-validate. Repeat until can_proceed_to_import is true.
  6. Review remaining warnings, skippable rows, and collisions - these will not block the import but tell you what will be skipped or auto-mapped.
  7. 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.