Skip to content

Data Import ​

The Data Import feature lets you migrate existing data - customers, subscriptions, orders, balances and more - from another system into TiruPay using CSV files.

Importing is a two-stage process:

  1. Validation - you upload your CSV files and TiruPay checks them thoroughly without writing anything. You get a detailed report of exactly what is correct, what needs fixing, and what will be skipped. You can correct your files and re-validate as often as you like. See Import Validation.
  2. Execution - once validation passes, you submit the same files again to write them into your service. The execution stage runs a final validation pass and then writes all valid rows in dependency order. See Import Execution.

Validation never changes anything

The validation stage is completely read-only. Uploading a file to validate it has no effect on your service's data. Nothing is created, changed or deleted until the execution stage runs.

Key Concepts ​

Entity Types ​

Each kind of record you can import is an entity type - for example customer, subscription, or order. Every CSV file you upload corresponds to one entity type. TiruPay tries to detect the entity type automatically from the file name and its columns, but you can always state it explicitly.

The full list of importable entity types and their columns is in the Field Reference.

External IDs ​

TiruPay identifies every record internally with its own ID. Your source system uses its own IDs. To bridge the two every imported row carries an External ID - the ID the record had in your old system.

The External ID does two things:

  • It lets rows in different files reference each other. For example, a subscription row points at the customer it belongs to using that customer's External ID, not a TiruPay ID.
  • It lets you re-run a validation safely. The same External ID always maps to the same record, so fixing one file and re-uploading does not create duplicates. (One exception: for article_balance_topup the External ID is optional - a topup imported without one is not deduplicated, so re-importing it creates a duplicate. See article_balance_topup.)

You choose the External ID

The External ID is simply whatever unique identifier your source system already uses for that record - a customer number, an order number, a UUID. It only needs to be unique within its entity type and consistent across your files.

References Between Files ​

Many records depend on others. A subscription needs a customer; an order position needs an order. These links are expressed with External IDs in dedicated columns - for example customer_external_id on a subscription points at the external_id of a customer.

A reference resolves if the target External ID is found either:

  • in the same upload (the referenced row is in one of the files you uploaded), or
  • already in your service (it was imported in a previous run).

If a reference cannot be resolved, the row is not rejected - it is skipped at import time and clearly reported. See Resolving references.

Catalog Items ​

Your product catalog - article categories, articles, article extensions and PAYG plans - can be imported directly (see Product Catalog). If your catalog already exists in TiruPay, you instead tag each catalog item with the External ID it had in your old system so that imported subscriptions and order positions can link to it.

See Linking to existing catalog items.

The Import Workflow ​

A typical migration looks like this:

  1. Export your data from the old system as CSV, one file per entity type.
  2. Prepare the catalog: either import it directly (article categories, articles, extensions, PAYG plans), or tag each existing catalog item with the External ID it had in the old system.
  3. Validate: upload the files and read the report.
  4. Correct: fix flagged rows, adjust column mappings, and re-validate until the report shows the import can proceed.
  5. Execute: run the execution stage to write the validated data.

Steps 3 and 4 are expected to repeat. The validation report is designed to be a checklist you work through.

Next Steps ​

  • Import Validation - how to upload, map columns, read the report, and understand every error.
  • Import Execution - running the import, what gets created, automatic side effects, and the audit log.
  • Field Reference - every importable entity type with its columns and accepted column names.