Prepare my file
Find the instructions to correctly construct your billing data import file.
Importing your billing data into Fincome begins with an essential step: correctly structuring your import file. This Excel (.xlsx) or Google Sheet file allows you to import your customers, subscriptions, invoices, invoice lines and credit notes according to the Fincome model. Good preparation ensures the reliability of your metrics (MRR, ARR, churn, revenue recognition…) and prevents any import errors.
1. File structure
The import file is a table in which each row represents a invoice line (a billed product or service), i.e. a component of the invoice.
It consolidates 5 main categories of information:
Customer: the billed entity.
Subscription: where applicable, the recurring relationship.
Invoice: the document grouping the billed lines.
Line item: the billed detail (e.g. “Pro Plan – 20 users – €600”).
Credit note
Optional: as many columns as necessary can be added to include enrichment data (don’t worry, this enrichment data can be added later).
The same invoice can contain multiple lines.
The same customer can appear multiple times (on different invoices).
When the same element repeats (e.g. an invoice, customer), the attributes describing it must remain strictly identical across all 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 format DD/MM/YYYY (type Date).
Text formats, ISO (e.g.
2025-09-15) or copied from a CSV are not recognized.
3. “type” column (mandatory)
Each row of the file must indicate a type of imported data. Three values are possible:
"subscription"
"subscription"Recurring subscription included in MRR/ARR.
The dark blue columns are mandatory.
The fields
period_startandperiod_endmust be provided, with:period_start<period_end(never identical)The periods must follow one another without overlap for the same subscription.
"one_off"
"one_off"One-off billing line (outside MRR).
Same structure as
subscription, but withoutperiod_startnorperiod_end.
"future_sub"
"future_sub"Future subscription not yet invoiced (signed contract with deferred start).
Only the following columns are mandatory:
type,customer_idand the dark purple columns of the template.
Make sure to use exactly one of these three terms for the "Type" column so the file is usable.
4. Importing 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 line in the file.
Fill in:
invoice_idwith the identifier of the relevant invoice,a negative amount in
amount_excluding_tax_after_discount,the blue-green columns (related to the canceled line).
Fincome will automatically adjust your metrics (MRR, ARR, revenue recognition, etc.).
5. Concrete examples
Example 1 — Monthly subscription
subscription
01/09/2025
30/09/2025
600
INV-2025-001
paid
active
CUST-001
Example 2 — One_off line
one_off
1500
INV-2025-002
open
CUST-002
Example 3 — Credit note
subscription
-600
INV-2025-001
paid
CUST-001
6. Custom analysis axes (optional)
You can enrich your data by adding additional columns:
→ acquisition_channel, country, customer_segment, CSM, etc.
These columns automatically become custom analytical axes usable in your Fincome filters and breakdowns.
7. Allowed values
Subscription status (
subscription_status) :trialing,active,paused,canceled,unpaidInvoice status (
invoice_status) :open,pending,paid,unpaidAny other value will be rejected on import.
8. Checklist before import
File in .xlsx
All mandatory columns filled in according to the line type
Identifiers (
customer_id,invoice_id,subscription_id) stable and consistentValid and ordered Excel dates (
period_start<period_end)Amounts in numeric, without thousand separators
Status and currency values conform to the Fincome model
FAQ — Preparing the file
→ Can an invoice contain multiple lines?
Yes. The same invoice_id can aggregate multiple line items (e.g. subscription + setup fees).
Just ensure that all fields describing the invoice (status, date, currency) are strictly identical on each row.
→ Are “one_off” lines taken into account in MRR/ARR?
No. Only lines type = "subscription" contribute to MRR/ARR. The one_off represent one-time revenues.
→ How to model an annual or quarterly subscription?
Provide 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 MRR/ARR movements and revenue recognition.
→ How to handle an upsell or a downsell?
Create multiple non-overlapping lines 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 changes (upsell/downsell).
→ How to represent a trial period?
Use type = "subscription", subscription_status = "trialing" and specify a trial period.
If the trial is not billed: amount_excluding_tax_after_discount = 0.
Free trials can be ignored if you do not wish to track them.
→ How to handle credit notes? Two solutions:
Add an adjustment line with a negative amount, associated with the
invoice_idoriginal.Create a
credit notededicated line according to the template instructions.
→ Which status values should be used?
Invoice (
invoice_status) :open,paid,unpaidSubscription (
subscription_status) :trialing,active,paused,canceled,unpaidAny 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, you can omit the dates or use the invoice date.
→ How to handle amounts excluding tax, discounts and VAT?
amount_excluding_tax_after_discount = net amount excluding tax after discount.
Taxes are managed separately, and the revenue recognition handles their accounting allocation.
→ Our billing is multi-currency: how to proceed?
Fill in the currency column (ISO code: EUR, USD, GBP…).
Fincome handles multi-currency consolidation and FX impact.
→ What if a customer or an invoice appears on multiple rows?
This is expected, but the fields of the same object (e.g. status, currency) must be identical.
Any discrepancy will be flagged 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 thousand separators, and check that the comma/period matches your regional format.
Next:
Import my fileLast updated