Skip to content

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/execute

The parameters are identical to /validate:

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

  1. customer, balance_type, feature, coupon
  2. user, mandate, credit_balance, credit_transaction, balance_usage_category
  3. payg_plan, payg_plan_price, payg_plan_price_item
  4. article_category, article, article_extension, article_feature_link, article_balance_topup, article_payg_activation, article_availability
  5. balance, payg_activation, balance_usage, balance_usage_item
  6. order, order_position, payment, order_refund, applied_coupon, order_feature_log
  7. subscription, 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.00
  • total_amount_after_discount = total_amount
  • total_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:

FieldMeaning
execution_idUUID of the ImportExecution audit record.
service_idThe service the import ran against.
entitiesPer-entity-type write counts (see below).
summaryTotals across all entity types.

Each entry in entities contains:

FieldMeaning
entity_typeThe entity type written.
written_rowsRows successfully written to the database.
skipped_rowsRows skipped (collision or unresolved reference).
error_rowsRows that failed at write time (should be zero after clean validation).
row_errorsPer-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:

FieldMeaning
idUUID of the execution.
service_idThe service it ran against.
created_byThe user who triggered it.
created_atTimestamp.
filenamesThe CSV files that were uploaded.
total_written / total_skipped / total_errorsRow 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_balance warnings 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_skipped in 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 ​