Appearance
Import Execution
Execution is the second and final stage of a data import. You submit the same CSV files you validated, and TiruPay writes all valid rows into your service in a single operation.
Validation runs again before any write
The execution stage always runs a full validation pass first. If any blocking errors exist, the import is rejected before a single row is written. Fix the errors, re-validate, and try again.
Running an Execution
Execution is an admin action against the service you are importing into.
POST /admin/import/executeThe parameters are identical to /validate:
| Parameter | Description |
|---|---|
service_id | The service you are importing into. |
files | One or more CSV files (same files as validated). |
entity_types | (optional) Explicit entity type per file. |
header_corrections | (optional) Column mapping corrections. |
mapping_template_id | (optional) A saved mapping template to apply. |
delimiter | (optional) Column separator. Defaults to ,. |
On success the endpoint returns an ImportExecutionReport (see Execution Report).
On failure (validation errors exist) the endpoint returns HTTP 422. The detail field describes how many blocking errors were found. Run /validate first to see them in full.
What Gets Written
Every valid, non-duplicate row for every entity type in the upload is written to the database. Rows are written in dependency order - parents before children - so foreign-key links are always satisfied at write time:
customer,balance_type,feature,couponuser,mandate,credit_balance,credit_transaction,balance_usage_categorypayg_plan,payg_plan_price,payg_plan_price_itemarticle_category,article,article_extension,article_feature_link,article_balance_topup,article_payg_activation,article_availabilitybalance,payg_activation,balance_usage,balance_usage_itemorder,order_position,payment,order_refund,applied_coupon,order_feature_logsubscription,subscription_extension,subscription_pending_change,feature_assignment
Rows with unresolved references or collision flags (identified during validation) are silently skipped - they count toward total_skipped, not total_errors.
Collision and Duplicate Handling
A row whose External ID matches a record already in your service is a collision. Collisions are always skipped: the existing record is left untouched. This makes it safe to re-run an import - rows that already landed are recognised and not duplicated.
Exception: topups without an External ID are not deduplicated
For article_balance_topup, the External ID is optional. A topup that carries one is deduplicated like any other entity (a re-import is skipped). A topup imported without one cannot be recognised on re-import, so it is always written - re-importing the same file creates duplicate topups. The validation report flags likely duplicates with an article_balance_topup_potential_duplicate warning, but it does not block them - either provide an External ID per topup or remove already-imported rows before re-running. See article_balance_topup.
Credit Balance Auto-Creation
Every customer must have a Credit Balance (prepaid wallet) in the customer's own currency (derived from their country). If no such balance exists after the import, an empty one is created automatically:
current_balance = 0.00- Currency derived from the customer's country.
This is a convenience - it means you do not have to export and re-import your Credit Balance table just to get customers in. If the opening balance is not zero, include a credit_balance row explicitly.
Balances in other currencies do not suppress auto-creation
If you import a credit_balance row with a currency that differs from the customer's country currency (e.g. USD for a EUR customer), the auto-creation still runs and creates the missing EUR balance alongside it. The validation stage flags such mismatches with a credit_balance_currency_mismatch warning.
The validation stage emits a customer_without_credit_balance warning for each customer who will receive an auto-created balance, so you can review them before executing.
Order Totals
Imported orders get the same derived totals as orders created in TiruPay (an imported order carries no coupon):
total_discount = 0.00total_amount_after_discount = total_amounttotal_tax_after_discount = total_tax
total_amount is the net sum of the order's positions (total_price); tax goes in total_tax.
Subscription Minimum Term
A subscription imported without min_term_periods takes the value of its article, like a subscription created in TiruPay. It decides the earliest cancellation date: max(current_period_end, started_at + interval × min_term_periods).
Feature Grants and Subscriptions
An imported order_feature_log row is linked to the subscription of its order. TiruPay ends a subscription's feature grants through this link when the subscription is cancelled or renewed, and the order page finds the subscription through it.
PAYG Balance Freeze
A pay-as-you-go balance without a payment mandate is automatically frozen at creation (system reason: mandate_revoked). This mirrors the behaviour of the normal CRUD path: usage cannot be recorded on an unfrozen PAYG balance that has no mandate.
If your imported PAYG balance already has a mandate (via mandate_external_id on a co-imported subscription, or a mandate already in your service), no freeze is created.
PAYG Activation Price Snapshot
When a payg_activation row is imported, the executor creates a PaygActivationCategoryPrice record for each payg_plan_price_item defined on the referenced PAYG plan for the customer's country. This price snapshot is what TiruPay uses to bill usage - it locks in the per-category prices that were in effect at activation time, so future price changes do not affect historical usage records.
The payg_plan_external_id column on payg_activation is required for this reason. Tag your existing PAYG plans with the External ID they had in your source system before importing activations.
Import order
Import payg_plan → payg_plan_price → payg_plan_price_item before importing payg_activation rows. The snapshot is built from the price items that exist at write time.
Execution Report
The execution response contains:
| Field | Meaning |
|---|---|
execution_id | UUID of the ImportExecution audit record. |
service_id | The service the import ran against. |
entities | Per-entity-type write counts (see below). |
summary | Totals across all entity types. |
Each entry in entities contains:
| Field | Meaning |
|---|---|
entity_type | The entity type written. |
written_rows | Rows successfully written to the database. |
skipped_rows | Rows skipped (collision or unresolved reference). |
error_rows | Rows that failed at write time (should be zero after clean validation). |
row_errors | Per-row error details: external_id and message for each failed row. |
The summary contains total_written, total_skipped, and total_errors across all entity types.
Import Audit Log
Every execution is recorded as an ImportExecution audit entry. You can query the log to review all past imports for a service.
The entry is also written when the import stops with an unexpected error. Entity types written before the error stay in the database, and the entry lists them together with an aborted result that holds the error.
Every customer created by an execution stores its ID as import_execution_id, visible to admins only.
List Executions
GET /admin/import/executions?service_id=...Returns a list of executions, newest first. Each entry contains:
| Field | Meaning |
|---|---|
id | UUID of the execution. |
service_id | The service it ran against. |
created_by | The user who triggered it. |
created_at | Timestamp. |
filenames | The CSV files that were uploaded. |
total_written / total_skipped / total_errors | Row counts for the run. |
Get Execution Details
GET /admin/import/executions/{execution_id}Returns the full record, including:
entity_type_map- which filename was treated as which entity type.header_corrections- any column corrections that were applied.mapping_template_id- the template used, if any.results- per-entity-type counts and per-row error details.
After the Import
Once the import completes, check these things:
- Import report - review the execution report for any unexpected errors or skipped rows.
- Imported data - spot-check the database to verify that records were created as expected, and linked together correctly.
- Customers with auto-created Credit Balances - find them via the
customer_without_credit_balancewarnings in the preceding validation report and set their opening balances if needed. - PAYG balances that are frozen - a frozen PAYG balance means no mandate was imported with it. Import mandates and assign them to the relevant subscriptions/balances to unfreeze.
- Skipped rows - review
total_skippedin the report. Rows skip because of collisions (expected for re-runs) or unresolved references (records that need to be in an earlier or later batch). - Catalog links - verify that subscriptions and order positions resolved to the correct articles by spot-checking a few records.
Next Steps
- Import Validation - how to prepare files, read the validation report, and understand every error code.
- Field Reference - every importable entity type with its columns.
- Data Import overview - concepts and the end-to-end workflow.