Importing your billing data into Fincome starts with an essential step: correctly structuring your import file. This Excel (.xlsx) or Google Sheet file lets you integrate your customers, subscriptions, invoices, invoice lines, and credit notes according to the Fincome model. Good preparation guarantees the reliability of your indicators (MRR, ARR, churn, revenue recognition…) and avoids any error at import.

Find the templates in Fincome > Settings > Connect a new billing system:

• Excel: you will find an example and the empty template
• Gsheet: you will find the template to complete before integrating the link

1. Structure of the file

The import file is a table in which each row represents an invoice line (a billed product or service), i.e. a component of the invoice.

It consolidates 7 major categories of information:

• Invoice
• Credit note
• Line item
• Subscription
• Customer
• Plan (Price)
• Product
• Optional: as many columns as needed can be added to integrate enrichment data (don't worry, this enrichment data can be added at a later stage).

The same invoice can have several rows.

The same customer can appear several times (on different invoices).

When the same element repeats (e.g. an invoice, customer), the attributes describing it must remain rigorously identical across all the corresponding rows.
Example: the same _invoice_id_ must always have the same _status_, the same _date_, and the same _currency_., but the information for the same identifier must remain perfectly identical on each row.

2. Date format

• All dates must be entered in the Excel DD/MM/YYYY format (Date type).
• Text formats, ISO (e.g. 2025-09-15), or formats copied from a CSV are not recognized.

3. "type" column (required)

Each row of the file must indicate a type of imported data. Three values are possible:

"subscription"

Recurring subscription included in the MRR/ARR.

The dark blue columns are required.

The period_start and period_end fields must be filled in, with:

• period_start < period_end (never identical)
• The periods must follow on from one another for the same subscription (e.g.: from 01/01/25 to 01/02/25, then from 01/02/25 to 01/03/25 and so on).

"one_off"

• One-time billing line (outside MRR).
• Same structure as subscription, but without period_start or period_end.

"future_sub"

• Future subscription not yet billed (signed contract with a deferred start).
• Only the following columns are required: type, customer_id, and the dark purple columns of the template.

4. Integrating credit notes

To add a credit note in Fincome, two solutions are possible:
1- Create a negative invoice line, identical to the one(s) it cancels but with the negative amount.
2- Create a dedicated row in the file.

Fill in:

• invoice_id with the identifier of the invoice being canceled,
• a negative amount in amount_excluding_tax_after_discount,
• the blue-green columns (related to the canceled line).

Fincome will automatically adjust your indicators (MRR, ARR, revenue recognition, etc.).

5. Concrete examples of the required rows

Example 1 — Monthly subscription

Example 2 — one_off row

Example 3 — Credit note

6. Custom analysis dimensions (optional)

You can enrich your data by adding extra columns: → acquisition_channel, country, customer_segment, CSM, etc. These columns automatically become custom analytical dimensions linked exclusively to customers, usable in your Fincome filters and breakdowns.

7. Allowed values

• Subscription status (**subscription_status**): active, paused, canceled
• Invoice status (**invoice_status**): open, pending, paid, unpaid
• Any other value will be rejected at import.

8. Checklist before import

• File in .xlsx format
• All the required columns completed according to the row type
• Stable and consistent identifiers (customer_id, invoice_id, subscription_id)
• Valid, ordered Excel dates (period_start < period_end)
• Amounts in numeric format, without thousands separators
• Status and currency values compliant with the Fincome model

FAQ — Preparing the file

→ Can an invoice have several rows?
Yes. The same invoice_id can aggregate several line items (e.g. subscription + setup fees). Simply make sure that all the fields describing the invoice (status, date, currency) are strictly identical on each row.

→ Are "one_off" rows taken into account in the MRR/ARR?
No. Only type = "subscription" rows contribute to the MRR/ARR. one_off rows represent one-time revenue.

→ How to model an annual or quarterly subscription?
Fill in the actual service period: period_start = 01/01/2026 and period_end = 31/12/2026 for an annual subscription, for example. Fincome relies on these dates to calculate the MRR/ARR movements and revenue recognition.

→ How to handle an upgrade ("upsell") or a reduction ("downsell")?
Create several non-overlapping rows for the same customer_id: 01/01 → 15/03 for the old plan, then 16/03 → 31/12 for the new one. Fincome automatically detects the variations (upsell/downsell).

→ How to represent a trial period?
Use type = "subscription", subscription_status = "trialing" and indicate a trial period. If the trial is not billed: amount_excluding_tax_after_discount = 0. Free trials can be ignored if you do not want to track them.

→ How to handle credit notes? Two solutions:

• Add an adjustment row with a negative amount, associated with the original invoice_id.
• Create a dedicated credit note row according to the template's instructions.

→ Which status values should be used?

• Invoice (**invoice_status**): open, paid, unpaid
• Subscription (**subscription_status**): trialing, active, paused, canceled, unpaid Any other value will be rejected.

→ What are the best practices for dates?
Use Excel dates (DD/MM/YYYY), not text. period_end must always be later than period_start. For one_off rows, you can omit the dates or use the invoice date.

→ How to handle net amounts, discounts, and VAT?
amount_excluding_tax_after_discount = net amount excluding tax, after discount. Taxes are handled separately, and revenue recognition takes care of their accounting breakdown.

→ Our billing is multi-currency: how should we proceed?
Fill in the currency column (ISO code: EUR, USD, GBP…). Fincome handles multi-currency consolidation and the FX impact.

→ What if a customer or an invoice appears on several rows?
That is expected, but the fields of the same object (e.g. status, currency) must be identical. Any discrepancy will be reported as an inconsistency.

→ What to do for a large import?
Split into batches (by period or entity) and start with a test sample of 5–10k rows.

→ How to avoid decimal separator errors?
Format your amounts as Number, not text. Avoid thousands separators, and check that the comma/point matches your regional format.

Next:

Import my file

Updated on: 03/07/2026