> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.fincome.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Prepare my file

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

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

- Excel: you will find an example and the empty template.
- Google Sheet: you will find the template to complete before adding the link.

## 1. File structure

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

It consolidates 7 main categories of information:

- Invoice
- Credit note
- Line item
- Subscription
- Customer
- Price
- Product

**Optional:** as many columns as needed can be added to integrate enrichment data (no worries, this data can also be added at a later stage).

A single invoice can have several rows, and a single customer can appear several times (on different invoices). When the same element repeats, the attributes describing it must remain strictly identical across all corresponding rows. For example, the same `invoice_id` must always carry the same `status`, the same `date`, and the same `currency`.

## 2. Date format

- All dates must be entered in **Excel format DD/MM/YYYY** (type **Date**).
- Text, ISO (e.g. `2025-09-15`), or CSV-copied formats 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 `period_start` and `period_end` fields must be filled in, with:

- `period_start` < `period_end` (never identical);
- periods that **follow on** 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-off (non-MRR)** billing line. Same structure as `subscription`, but **without** `period_start` or `period_end`.

**`future_sub`**
**Future, not yet billed subscription** (signed contract with a deferred start). Only the following columns are mandatory: `type`, `customer_id`, and the dark purple columns of the model.

Make sure to use one of these three terms in the "type" column so that the file is usable.

## 4. Adding 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 a negative amount.
2. Create a **dedicated line** in the file, filling in:
   - `invoice_id` with the identifier of the cancelled invoice,
   - a **negative amount** in `amount_excluding_tax_after_discount`,
   - the blue-green columns (related to the cancelled line).

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

## 5. Concrete examples of the mandatory rows

### Example 1 — Monthly subscription

| invoice_id   | date       | type         | amount_excluding_tax_after_discount | description | period_start | period_end | customer_id |
| ------------ | ---------- | ------------ | ----------------------------------- | ----------- | ------------ | ---------- | ----------- |
| INV-2025-002 | 01/02/2025 | subscription | 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 analytical 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 the customer, 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 **mandatory columns** completed according to the row type
- Identifiers (`customer_id`, `invoice_id`, `subscription_id`) **stable and consistent**
- 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 fee). Just make sure that all the fields describing the invoice (`status`, `date`, `currency`) are strictly identical on each row.

**Is the Invoice ID mandatory, even a fictitious one?**
Yes. The `invoice_id` field is mandatory for the import to succeed, even when the number is fictitious. If your rows do not have a real invoice number (for example for a reconstructed history), fill in a fictitious identifier: the import will not run as long as this field is empty.

**Can I add extra columns? What happens to them?**
Yes. Any extra column is kept and attached to the customer profile, where it becomes a custom analytical dimension (see the "Custom analytical dimensions" section).

**Are "one_off" lines counted in MRR/ARR?**
No. Only `type = "subscription"` lines contribute to MRR/ARR. `one_off` lines represent one-off revenue.

**How do I 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 MRR/ARR movements and revenue recognition.

**How do I handle an upsell or a 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 do I represent a trial period?**
Use `type = "subscription"`, `subscription_status = "trialing"` and indicate a trial period. If the trial is unbilled: `amount_excluding_tax_after_discount = 0`. Free trials can be ignored if you do not want to track them.

**How do I handle credit notes?**
Two solutions: add an adjustment row with a negative amount, associated with the original `invoice_id`; or create a dedicated credit note row following the model's instructions.

**Which status values should I use?**
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` lines, you can omit the dates or use the invoice date.

**How do I handle amounts excluding tax, discounts, and VAT?**
`amount_excluding_tax_after_discount` corresponds to the amount excluding tax, net of discount. Taxes are handled separately, and revenue recognition takes care of their accounting allocation.

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

**What should I do if a customer or an invoice appears on several 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 should I do for a large import?**
Split it into batches (by period or entity) and start with a test sample of 5 to 10k rows.

**How do I avoid decimal separator errors?**
Format your amounts as Number, not text. Avoid thousands separators, and check that the comma/period matches your regional format.

## Next

[Import my file](https://help.fincome.co/en/article/import-my-file-p8jf4p/)