Prepare my file

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

Importing your billing data into Fincome begins with one essential step: correctly structuring your import file. This Excel (.xlsx) or Google Sheet file allows you to import your customers, subscriptions, invoices, invoice line items 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 empty template

  • Gsheet: you will find the template to complete before embedding 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 5 major categories of information:

    • Customer: the billed entity.

    • Subscription: if 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 needed 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 item repeats (e.g. an invoice, customer), the attributes describing it must remain rigorously 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 DD/MM/YYYY format (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"

  • 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)

    • Periods must follow each other without overlap for the same subscription.

"one_off"

  • One-off 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 for the file to be usable.

4. Including 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.

Provide:

  • invoice_id with the identifier of the related invoice,

  • a negative amount in amount_excluding_tax_after_discount,

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

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

5. Concrete examples

Example 1 — Monthly subscription

type
period_start
period_end
amount_excluding_tax_after_discount
invoice_id
status
subscription_status
customer_id

subscription

01/09/2025

30/09/2025

600

INV-2025-001

paid

active

CUST-001

Example 2 — One_off line

type
amount_excluding_tax_after_discount
invoice_id
status
customer_id

one_off

1500

INV-2025-002

open

CUST-002

Example 3 — Credit note

type
amount_excluding_tax_after_discount
invoice_id
status
customer_id

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, unpaid

  • 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 required columns completed according to the line 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 compliant with the Fincome model

FAQ — File preparation

→ 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 revenue.

→ How to model an annual or quarterly subscription? Enter 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 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 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 dedicated credit note line according to the template instructions.

→ What 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 . period_startFor one_offyou 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 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 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 thousands separators, and check that the comma/point matches your regional format.

Next:

Import my file
PreviousImport a billing fileNextImport my file

Last updated