Prepare my file

Find the instructions to correctly build your billing data import file.

Importing your billing data into Fincome begins with an essential step: properly 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 errors during import.

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

• Excel: you will find an example and the blank template

• Gsheet: you will find the template to complete before inserting the link

1. File structure

• 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

  • Price

  • Product

  • Optional: as many columns as necessary can be added to include enrichment data (don’t worry, these 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 (required)

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

"subscription"

• Recurring subscription included in MRR/ARR.

• The dark blue columns are mandatory.

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

  • period_start < period_end (never identical)

  • The periods must follow consecutively 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 nor period_end.

"future_sub"

• Future subscription not yet invoiced (signed contract with deferred start).

• Only the following columns are mandatory: type, customer_id and the dark purple columns of the template.

Make sure to use exactly one of these three terms for the "Type" column so that the file can be processed.

4. Including credit notes

To add a credit note in Fincome two options 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.

Provide:

• invoice_id with the identifier of the invoice being canceled,

• a negative amount in amount_excluding_tax_after_discount,

• the teal-blue columns (related to the canceled line).

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

5. Concrete examples of required rows

Example 1 — Monthly subscription

invoice_id	date	type	amount_excluding_tax_after_discount	description	period_start	Textperiod_end	customer_id
INV-2025-002	01/02/2025	one_off	1500	Sub X	01/02/2025	01/03/2025	CUST-002

Example 2 — One-off line

invoice_id	date	type	amount_excluding_tax_after_discount	description	customer_id
INV-2025-002	01/02/2025	one_off	1500	Set up by X	CUST-002

Example 3 — Credit note

invoice_id	credit_note_id	credit_note_date	currency_code	amount_excluding_tax_after_discount
INV-2025-001	CN_1	17/08/2022	EUR	-600

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 linked to the customer only, 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

• All required columns filled in according to the row type

• Identifiers (customer_id, invoice_id, subscription_id) stable and consistent

• Valid and ordered Excel dates (period_start < period_end)

• Amounts in numeric, without thousands separators

• Status and currency values conforming to the Fincome model

FAQ — Preparing the file

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

---

→ Are “one_off” lines included in MRR/ARR? No. Only lines type = "subscription" contribute to MRR/ARR. The one_off represent one-time revenue.

---

→ 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 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 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_id original.

• Create a credit note dedicated line according to the template 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 after to 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 (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 fields for 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 thousands separators, and check that the comma/point matches your regional format.

Next:

Import my file