Skip to content

Field Reference ​

This page lists every importable entity type, its columns, and the column names TiruPay recognises. Use it to prepare your CSV files.

How to Read These Tables ​

Each entity type has a table with four columns:

ColumnMeaning
FieldThe TiruPay field the column fills.
RequiredWhether a value is required on every row.
TypeThe expected value format (see Value types).
Also accepted asAlternative column names TiruPay recognises automatically, including German variants. You do not have to rename your columns to these - any of them works.

Beyond the listed names, TiruPay also maps close near-misses automatically and reports when it does. If a column still cannot be mapped, supply a column correction.

Value Types ​

TypeFormat
TextAny text.
Whole numberAn integer, e.g. 3.
NumberA decimal. Both 12.50 and 12,50 are accepted.
Date/time2024-01-15 or 2024-01-15T10:00:00. 15.01.2024 is also accepted.
Yes/Notrue/false, yes/no, ja/nein, 1/0.
ChoiceOne of a fixed set of values, listed with the field. Common English and German wordings are accepted and mapped automatically.

External IDs and References ​

  • external_id is required on every row of every entity type - it is your source system's own ID for the record.
  • Columns ending in _external_id are references: they hold the external_id of a related record. See References between files.

The product catalog (article categories, articles, extensions and PAYG plans) can be imported - see Product Catalog below. References to article / article_extension / payg_plan resolve against catalog items imported in the same upload or already present in your service (tagged with the External ID they had in your source system - see Linking to existing catalog items).

Core Customer Data ​

customer ​

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
emailYesTextemail_address, e_mail, mail, e-mail
first_nameNoTextfirstname, vorname, given_name, givenname
last_nameNoTextlastname, nachname, surname, family_name, familyname
streetYesTextaddress, street_address, strasse, adresse
cityYesTextstadt, town, ort, locality
postal_codeYesTextzip, postleitzahl, plz, zip_code, postcode
country_codeYesText (2-letter ISO, e.g. DE)country, land, iso_country, country_iso, laendercode
is_companyNoYes/Nocompany, is_business, firma, geschaeftskunde, b2b
company_nameNoTextfirma_name, business_name, organisation, firmenname, unternehmen
company_vat_idNoTextvat, ustid, tax_id, vat_number, ust_id, umsatzsteuer_id
company_tax_exemptNoYes/No (default No)tax_exempt, reverse_charge, steuerbefreit, steuerfrei
phoneNoTextphone_number, telefon, tel, telefonnummer, mobil
localeNoTextlanguage, sprache, lang
ext_invoicing_idNoTextinvoicing_id, billing_id, rechnungs_id
internal_noteNoTextnote, notes, notiz, notizen, interne_notiz

Company vs. private customers

If is_company is set, company_name becomes required; company_vat_id stays optional. Otherwise, at least one of first_name or last_name is required.

company_tax_exempt (reverse charge) is imported as given. Unlike the customer API, the import (currently) does not verify it against the VAT registry.

user ​

A portal login account linked to a customer.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, customer_ext_id, kunde_id
emailYesTextemail_address, e_mail, mail
first_nameNoTextfirstname, vorname, given_name
last_nameNoTextlastname, nachname, surname, family_name

mandate ​

A stored payment authorisation (e.g. SEPA direct debit or card token).

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, kunde_id, customer_ext_id
partnerYesChoice: mollie, stripe, nemopayment_partner, provider, zahlungsanbieter
payment_method_identifierYesChoice: payment method, e.g. sepa_direct_debit, credit_card, paypalmethod_identifier, zahlungsmethode, zahlungsmethode_id, payment_method, methode
partner_mandate_idYesTextmandate_id, mandat_id, external_mandate_id
statusNoChoice: valid, pending, invalid, revoked, expiredmandate_status, mandat_status

Subscriptions ​

subscription ​

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, kunde_id, customer_ext_id
paying_customer_external_idNoReference → customerpaying_customer_id, payer_id, payer_external_id, zahler_id
article_external_idYesReference → article (catalog)article_id, product_id, artikel_id
statusYesChoice: active, cancelled, paused, terminated, expiredsubscription_status, abo_status, state
intervalYesChoice: day, week, month, quarter, half_year, yearbilling_interval, period, abrechnungsintervall
started_atYesDate/timestart_date, start, activation_date, startdatum
current_period_startYesDate/timeperiod_start, periode_start, billing_start
current_period_endYesDate/timeperiod_end, renewal_date, next_billing_date, periode_ende
currency_codeNoText (3-letter ISO)waehrung, currency
country_codeNoText (2-letter ISO)country, tax_country, tax_country_code, land, steuerland
locked_article_priceNoNumberprice, locked_price, preis
min_term_periodsNoWhole numbermin_term, mindestlaufzeit
coupon_external_idNoReference → couponcoupon_id, gutschein_id
cancelled_atNoDate/timecancellation_date, kuendigungsdatum
cancellation_effective_atNoDate/timeeffective_cancellation, kuendigung_wirksam_ab
payment_method_identifierNoChoice: payment method, e.g. sepa_direct_debit, credit_card, paypalmethod_identifier, zahlungsmethode, zahlungsmethode_id, payment_method, methode
payment_partnerNoChoice: mollie, stripe, nemopartner, zahlungsanbieter
mandate_external_idNoReference → mandatemandate_id, mandat_id

Subscription rules

The referenced article must be a subscription article. If status is cancelled, cancelled_at is required. An active subscription needs a completed order and a payment mandate to renew - import these alongside it (the mandate via mandate_external_id, or payment_method_identifier + payment_partner).

Paid by someone else

Set paying_customer_external_id on an order or subscription when another customer pays for it - see Paying Customer. Leave it empty, or repeat customer_external_id, when the customer pays for themselves. When someone else pays:

  • the mandate must belong to the paying customer
  • the article must be available in the paying customer's country, and the order or subscription is taxed there, unless it sets country_code
  • articles and extensions with pay-as-you-go usage are not allowed

Tax country of a subscription

Set country_code to tax a subscription's renewals in a different country than its paying customer's. It stays fixed for the subscription's lifetime, and the article must be available in that country. Leave it empty to use the paying customer's country.

subscription_extension ​

An add-on booked on a subscription.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
subscription_external_idYesReference → subscriptionsubscription_id, abo_id
article_extension_external_idYesReference → article extension (catalog)extension_id, erweiterung_id
locked_priceNoNumberprice, preis
quantityNoNumbermenge, anzahl

locked_price is the net price per unit; the renewal charges locked_price × quantity. Without quantity the extension is booked once.

subscription_pending_change ​

A scheduled plan change that takes effect at the next renewal.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
subscription_external_idYesReference → subscriptionsubscription_id, abo_id
new_article_external_idYesReference → article (catalog)new_article_id, neuer_artikel_id
effective_atYesDate/timeeffective_date, wirksamkeit

Orders & Payments ​

order ​

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, kunde_id
paying_customer_external_idNoReference → customerpaying_customer_id, payer_id, payer_external_id, zahler_id
subscription_external_idNoReference → subscriptionsubscription_id, abo_id
order_numberYesText, unique per servicebestellnummer, rechnungsnummer, invoice_number
order_statusYesChoice: draft, pending, completed_outstanding, completed_finalized, partially_refunded, refunded, revoked, dunning, cancelledstatus, bestellstatus
order_dateNoDate/timedate, bestelldatum, rechnungsdatum
total_amountNoNumbertotal, gesamt, betrag
total_taxNoNumbertax, steuer, mwst
currency_codeNoText (3-letter ISO)waehrung, currency
country_codeNoText (2-letter ISO)country, tax_country, tax_country_code, land, steuerland
due_dateNoDate/timefaelligkeitsdatum, payment_due

Tax country

Set country_code to tax an order in a different country than its paying customer's, like the country override on a draft order. Leave it empty to use the paying customer's country.

order_position ​

A line item within an order. Reference exactly one of article or article extension.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
order_external_idYesReference → orderorder_id, bestell_id, rechnungs_id
article_external_idNo*Reference → article (catalog)article_id, artikel_id
article_extension_external_idNo*Reference → article extension (catalog)extension_id, erweiterung_id
quantityNoNumbermenge, anzahl
unit_priceNoNumbereinzelpreis, preis_pro_einheit
total_priceNoNumbergesamtpreis, gesamt
sort_orderNoWhole numberposition, reihenfolge
overwrite_nameNoTextname, bezeichnung
overwrite_descriptionNoTextdescription, beschreibung

* Exactly one of article_external_id or article_extension_external_id must be set.

payment ​

A recorded payment transaction against an order.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
order_external_idYesReference → orderorder_id, bestell_id
pp_payment_idYesTextpayment_processor_id, zahlungs_id, transaction_id
payment_method_identifierNoChoice: payment method, e.g. sepa_direct_debit, credit_card, paypalmethod_identifier, zahlungsmethode, zahlungsmethode_id, payment_method, methode
payment_partnerNoChoice: mollie, stripe, nemopartner, zahlungsanbieter

order_refund ​

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
order_external_idYesReference → orderorder_id, bestell_id
refund_typeYesChoice: full, position, position_partial, subscription_upgrade, subscription_terminationtype, erstattungstyp
net_amountYesNumbernettobetrag, betrag
tax_amountNoNumbersteuer, steuerbetrag
gross_amountNoNumberbruttobetrag
descriptionNoTextbeschreibung, grund, reason
ext_credit_note_idNoTextcredit_note_id, gutschrift_id

Amount consistency

If net_amount, tax_amount and gross_amount are all present, the gross must equal net + tax.


Balance System ​

balance_type ​

Defines a category of unit-based balance (e.g. SMS credits).

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
nameYesTextbezeichnung, typ_name, typname
descriptionNoTextbeschreibung
payment_modeYesChoice: prepaid, paygzahlungsmodus, modus
payg_payment_grace_daysNoWhole numbergrace_days, zahlungsfrist

INFO

payg_payment_grace_days only applies to payg types; on a prepaid type it is ignored.

balance_usage_category ​

A consumption category within a balance type.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
balance_type_external_idYesReference → balance_typebalance_type_id, kontotyp_id
nameYesTextbezeichnung, kategorie_name
descriptionNoTextbeschreibung
price_per_unitNo*Numberpreis_pro_einheit, unit_price

* Required when the referenced balance type is prepaid; must be empty when it is payg.

balance ​

A unit-based balance account for a customer.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, kunde_id
balance_type_external_idYesReference → balance_typebalance_type_id, kontotyp_id
statusNoChoice: active, partially_frozen, frozenbalance_status
paygNo*Yes/Nois_payg, pay_as_you_go
current_balanceNoNumberbalance, guthaben, kontostand
limit_paygNo**Numberpayg_limit, limit

* Set payg to true for pay-as-you-go balances. If omitted, it defaults based on the balance type's payment_mode.

** limit_payg only applies when payg is true.

balance_usage ​

A single usage event drawing on a balance.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
balance_external_idYesReference → balancebalance_id, konto_id
titleYesTextbezeichnung, name
billing_statusYesChoice: pending, billed_pending, billed, reserved, denied, refunded, revokedstatus, usage_status
total_costNoNumberkosten, betrag

balance_usage_item ​

A line within a usage event.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
balance_usage_external_idYesReference → balance_usageusage_id, verbrauch_id
usage_category_external_idYesReference → balance_usage_categorycategory_id, kategorie_id
units_usedYesNumbereinheiten, menge
costNoNumberkosten
is_reservationNoYes/Noreservierung, reserved

payg_activation ​

A record that a pay-as-you-go balance has been activated. Required for every PAYG balance - without one, usage would fail at runtime.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
balance_external_idYesReference → balancebalance_id, konto_id
payg_plan_external_idYesReference → payg_planpayg_plan_id, plan_id, plan_ext_id
statusNoChoice: active, cancelledactivation_status
monthly_free_amountNoNumbermonthly_free, monatlicher_freibetrag
limit_paygNoNumberlimit, payg_limit

Required alongside every PAYG balance

Import a payg_activation row alongside every PAYG balance - or ensure the activation already exists in your service. A PAYG balance without an active activation produces a payg_activation_missing error.

payg_plan_external_id must reference the External ID of a PAYG plan - either imported in the same upload (see payg_plan) or already configured in your service. The executor automatically creates a price snapshot (PaygActivationCategoryPrice) from the plan's current prices when the activation is imported - so usage is always billed at the prices that were in effect at activation time.


Credit Balance (Prepaid Wallet) ​

credit_balance ​

A global prepaid wallet for a customer.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, kunde_id
currency_codeYesText (3-letter ISO)waehrung, currency
current_balanceNoNumberbalance, guthaben, kontostand
statusNoChoice: active, partially_frozen, frozenbalance_status

credit_transaction ​

A movement on a credit balance.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
credit_balance_external_idYesReference → credit_balancebalance_id, guthaben_id
transaction_typeYesChoice: credit, debit, refundtype, buchungstyp
amountYesNumber (greater than 0)betrag
balance_beforeNoNumbervorher, stand_vorher
balance_afterNoNumbernachher, stand_nachher
descriptionNoTextbeschreibung, verwendungszweck

INFO

When amount, balance_before and balance_after are all present, the resulting balance must match: a credit or refund adds the amount, a debit subtracts it.


Coupons ​

coupon ​

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
codeYesTextgutscheincode, coupon_code, rabattcode
nameYesTextbezeichnung, gutscheinname
descriptionNoTextbeschreibung
coupon_typeYesChoice: percentage, amounttyp, rabatttyp
discount_percentageNo*Numberrabatt_prozent, prozent, percentage
discount_amountNo*Numberrabatt_betrag, betrag, amount
min_order_amountNoNumbermindestbestellwert, min_betrag
currency_codeNo*Text (3-letter ISO)waehrung, currency
valid_fromNoDate/timegueltig_ab, start
valid_untilNoDate/timegueltig_bis, ablauf, expiry
is_globalNoYes/Noglobal, global_gueltig
max_redemptionsNoWhole numbermax_einloesungen, max_uses

* For a percentage coupon, discount_percentage (0-100) is required and discount_amount must be empty. For an amount coupon, discount_amount and currency_code are required and discount_percentage must be empty.

applied_coupon ​

A record of a coupon applied to an order.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
order_external_idYesReference → orderorder_id, bestell_id
coupon_external_idYesReference → couponcoupon_id, gutschein_id
applied_atNoDate/timeangewendet_am, used_at
total_discount_grantedNoNumberrabatt, discount

Features ​

feature ​

A feature definition for the service.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
public_nameYesTextname, oeffentlicher_name, bezeichnung
internal_nameYesTextinternal_id, interner_name, key
descriptionNoTextbeschreibung
typeYesChoice: boolean, integerfeature_type, typ

feature_assignment ​

Assigns a feature directly to a customer.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
customer_external_idYesReference → customercustomer_id, kunde_id
feature_external_idYesReference → featurefeature_id, merkmal_id
quantityNoWhole numbermenge, anzahl

order_feature_log ​

A record of a feature grant triggered by an order.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
order_external_idYesReference → orderorder_id, bestell_id
customer_external_idYesReference → customercustomer_id, kunde_id
feature_external_idYesReference → featurefeature_id, merkmal_id
quantityNoWhole numbermenge, anzahl
granted_atNoDate/timegewaehrt_am, start
ended_atNoDate/timebeendet_am, end

Product Catalog ​

The product catalog defines what you sell. Import the catalog in dependency order: categories first, then articles, then extensions and the links that articles provide (features, balance topups, PAYG activations). PAYG plans and their prices can be imported in the same upload.

article_category ​

A grouping for articles. Service-scoped.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
nameYesTextbezeichnung, kategorie_name, category_name, kategoriename
descriptionNoTextbeschreibung
unique_subscriptionNoBooleanabo_eindeutig, eindeutiges_abo, exklusives_abo

article ​

A sellable product or subscription plan.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
article_category_external_idYesReference → article_categorycategory_id, kategorie_id, article_category_id, category_ext_id
nameYesTextbezeichnung, artikelname, produkt, produktname, title
descriptionNoTextbeschreibung
net_priceYesNumbernettopreis, preis, price, net, netto
hiddenNoYes/Noversteckt, is_hidden, ausgeblendet
is_subscriptionNoYes/Noabo, subscription, ist_abo, is_abo
allow_multipleNoYes/Nomehrfach, mehrfach_erlaubt, multiple
intervalNo*Choice: day, week, month, quarter, half_year, yearbilling_interval, abrechnungsintervall, intervall, period
min_term_periodsNo*Whole numbermin_term, mindestlaufzeit, min_laufzeit

* interval is required when is_subscription is true, and must be empty otherwise. min_term_periods is only allowed on subscription articles. A mismatch produces an article_interval_required / article_interval_not_allowed error.

article_extension ​

An add-on attached to a subscription article. The parent article must be a subscription.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
article_external_idYesReference → articlearticle_id, artikel_id, parent_article_id
nameYesTextbezeichnung, erweiterungsname, title
descriptionNoTextbeschreibung
net_priceYesNumbernettopreis, preis, price, net, netto
hiddenNoYes/Noversteckt, is_hidden, ausgeblendet
allow_multipleNoYes/Nomehrfach, mehrfach_erlaubt, multiple

article_feature_link ​

A feature granted by an article, with its value. Provide exactly one of value_bool (for boolean features) or value_int (for integer features).

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
article_external_idYesReference → articlearticle_id, artikel_id
feature_external_idYesReference → featurefeature_id, merkmal_id
value_boolNo*Yes/Nobool_value, wert_bool, boolean
value_intNo*Whole numberint_value, wert_int, menge, anzahl

* Exactly one of value_bool or value_int must be set.

article_balance_topup ​

The balance amount a customer receives when an article or extension is purchased. Reference exactly one of article or extension.

FieldRequiredTypeAlso accepted as
external_idNoTextext_id, id, source_id, src_id, uid
article_external_idNo*Reference → articlearticle_id, artikel_id
article_extension_external_idNo*Reference → article_extensionextension_id, erweiterung_id, article_extension_id
balance_type_external_idYesReference → balance_typebalance_type_id, kontotyp_id
topup_amountYesNumber (> 0)betrag, amount, aufladebetrag, guthaben

* Exactly one of article_external_id or article_extension_external_id must be set.

Deduplication depends on whether you provide an External ID

Unlike other entities, external_id is optional here. How re-imports behave depends on it:

  • With an external_id (recommended): the topup is deduplicated exactly like every other entity - a re-import of the same External ID is skipped, so no duplicate is created. If your source system already has a per-topup ID, supply it.
  • Without an external_id: there is no reliable key to recognise a topup that was already imported, so every topup row is always written and re-importing the same file creates a duplicate topup. As a safety net, when such a topup matches an existing one (same article/extension + balance type + amount), the validation report raises an article_balance_topup_potential_duplicate warning (it does not block). Always review these warnings and verify manually before proceeding.

article_payg_activation ​

Links an article or extension to a PAYG plan that activates when it is purchased. Reference exactly one of article or extension.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
article_external_idNo*Reference → articlearticle_id, artikel_id
article_extension_external_idNo*Reference → article_extensionextension_id, erweiterung_id, article_extension_id
payg_plan_external_idYesReference → payg_planpayg_plan_id, plan_id, plan_ext_id

* Exactly one of article_external_id or article_extension_external_id must be set.

payg_plan ​

A pay-as-you-go billing plan tied to a balance type.

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
balance_type_external_idYesReference → balance_typebalance_type_id, kontotyp_id
nameYesTextbezeichnung, planname, plan_name
descriptionNoTextbeschreibung
monthly_free_amountNoNumbermonatlicher_freibetrag, monthly_free, freibetrag
limit_paygNoNumberlimit, payg_limit, obergrenze
unit_scaleNoWhole number (1 - 1000000)einheitenskala, scale, skalierung
is_activeNoYes/Noaktiv, active

payg_plan_price ​

A per-country container for a PAYG plan. Holds optional country-level overrides for free allowance and limit. Per-category prices are defined separately in payg_plan_price_item. country_code is resolved against TiruPay configuration (no External ID needed).

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
payg_plan_external_idYesReference → payg_planpayg_plan_id, plan_id, plan_ext_id
country_codeYesISO 2-letter country codecountry, land, iso_country, country_iso, laendercode
monthly_free_amountNoNumbermonatlicher_freibetrag, monthly_free
limit_paygNoNumberlimit, payg_limit
monthly_free_unitsNoNumbermonatliche_freie_einheiten

Config lookups

country_code must match a country configured in TiruPay. An unresolvable value produces a payg_plan_price_country_not_found error.


payg_plan_price_item ​

A per-category price entry within a payg_plan_price. tax_category_name is resolved against TiruPay configuration (no External ID needed).

FieldRequiredTypeAlso accepted as
external_idYesTextext_id, id, source_id, src_id, uid
payg_plan_price_external_idYesReference → payg_plan_pricepayg_plan_price_id, price_id, plan_price_id
usage_category_external_idYesReference → balance_usage_categoryusage_category_id, category_id, kategorie_id
price_per_unitYesNumberpreis_pro_einheit, preis, price, unit_price
tax_category_nameYesText (name of a tax category in that country)tax_category, steuerkategorie, steuerkategorie_name, tax_class
monthly_free_unitsNoNumbermonatliche_freie_einheiten

Config lookups

tax_category_name must match a tax category that exists for the country of the parent payg_plan_price. An unresolvable value produces a payg_plan_price_tax_category_not_found error.