# Stripe integration mapping

### Connect to Stripe

[Follow this guide](https://help.fincome.co/en/guide/sources/connect-my-stripe-account) to establish the connection with the Stripe API. 

### Synchronized data

| **Stripe entity**  | **Synchronized key fields**                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Customers          | id, name, email, address.country, address.postal\_code                                                                                                     |
| Products           | id, name                                                                                                                                                   |
| Prices             | id, plan name, recurring.interval, recurring.interval\_count, amount, currency                                                                             |
| Subscriptions      | id, customer\_id, status, trial\_start, trial\_end, canceled\_at, start\_date, monthly\_value                                                              |
| Invoices           | id, customer\_id, date, status, number                                                                                                                     |
| Invoice Line Items | id, invoice\_id, subscription\_id, price\_id, amount\_excluding\_tax\_after\_discount, tax\_amount, discount\_amount, quantity, period\_start, period\_end |
| Credit Notes       | id, invoice\_id, date, status and associated lines (amount, discount\_amount, …)                                                                           |
| Events             | Handling of object updates and incremental sync via webhooks                                                                                               |

***

### Detailed operation of the integration

The Stripe integration with Fincome is designed to ensure a faithful and granular reading of your billing data. Here are the main mechanisms in place:

* **Structured object mapping**\
  Each Stripe entity (customer, product, subscription, invoice...) is translated into Fincome via a field-to-field mapping, according to the rules defined in our integration engine.
* **Detection of trial periods**\
  Trial periods are automatically extracted from `trial_start` and `trial_end`.
* **Detailed subscription tracking**\
  Each subscription line (`items.data`) is tracked separately to reflect upgrades or downgrades, reactivations, suspensions, etc.
* **Cancellations & suspensions**\
  The statuses `canceled`, `unpaid`, `incomplete_expired` are correctly interpreted. The fields `cancel_at`, `canceled_at` and `pause_collection` allow faithful representation of end-of-commitment.
* **MRR calculation**\
  MRR is determined for each subscription line from the price (with its periodicity) and converted into the base currency according to the exchange rate applicable on the creation date.
* **Comprehensive discount analysis**\
  Fincome distinguishes and values:
  * discounts **temporary** (e.g.: coupons with limited duration)
  * discounts **permanent** (e.g.: reduced prices, coupons without expiration)
* **Currency conversion**\
  Amounts are converted on the fly into the reference currency (EUR, USD...) using the `currency` field and the issuance date of each document (invoice, credit note...).
* **Incremental and priority synchronization**\
  Stripe updates are automatically detected via Webhooks (e.g.: `invoice.updated`, `customer.subscription.updated`).\
  Any manual modification made in Fincome remains prioritized over the synchronized data.

***

### Note

* **Duration of the initial synchronization**\
  It can take several hours depending on the volume of subscribers, invoices or history to import.
* **Daily synchronization**\
  Fincome synchronizes Stripe automatically **each night**, including new data and updates.
* **Manual override**\
  Any manual change made in Fincome (e.g.: reassignment of a subscription) **is never overwritten** by the Stripe synchronization.
* **Stripe rate limit**\
  API limits imposed by Stripe are automatically managed. Fincome pauses and resumes synchronization without manual action.
* **OAuth token expiration**\
  The OAuth connection is automatically refreshed if needed. No intervention is required from you.

***

### Integration overview

| **Item**               | **Detail**                                                         |
| ---------------------- | ------------------------------------------------------------------ |
| Integration method     | OAuth 2.0 (direct connection from Fincome)                         |
| Supported entities     | Customers, Products, Prices, Subscriptions, Invoices, Credit Notes |
| Sync frequency         | Daily + Webhooks                                                   |
| Initial import         | Complete Stripe history                                            |
| Synchronization method | REST API with starting\_after pagination                           |
| Stripe data deletion   | Not supported (not propagated into Fincome)                        |

***

### Data settings

| **Setting**         | **Operation**                               |
| ------------------- | ------------------------------------------- |
| Trial detection     | trial\_start and trial\_end                 |
| MRR calculation     | Periodicity + amount + currency at the date |
| End of commitment   | cancel\_at or canceled\_at                  |
| Cancellation        | Status + pause\_collection, cancel\_at      |
| Subscriptions       | Per-line tracking (items.data)              |
| Discounts           | Coupons: temporary or permanent             |
| Currency conversion | currency + invoice date                     |
| Resynchronization   | Automatic (priority to manual changes)      |

***

### Technical mapping (Stripe → Fincome)

#### Customers

| **Stripe**                                           | **Fincome**  |
| ---------------------------------------------------- | ------------ |
| id                                                   | original\_id |
| name                                                 | name         |
| email                                                | email        |
| address.country / shipping.address.country           | country      |
| address.postal\_code / shipping.address.postal\_code | zip\_code    |

#### Products & Prices

| **Stripe**                | **Fincome**            |
| ------------------------- | ---------------------- |
| product.id                | original\_id (product) |
| product.name              | name (product)         |
| price.id                  | original\_id (price)   |
| nickname / plan           | name (price)           |
| recurring.interval        | period\_unit           |
| recurring.interval\_count | period\_length         |
| unit\_amount              | amount                 |
| currency                  | currency\_code         |
| product                   | product\_id            |

#### Subscriptions

| **Stripe**                | **Fincome**                   |
| ------------------------- | ----------------------------- |
| id                        | original\_id                  |
| customer                  | customer\_id                  |
| status, pause\_collection | status                        |
| trial\_start              | trial\_start                  |
| trial\_end                | trial\_end                    |
| created                   | deal\_closed\_date            |
| start\_date               | subscription\_start\_date     |
| cancel\_at                | effective\_cancellation\_date |
| canceled\_at              | canceled\_at                  |
| price.id / plan.id        | price\_id                     |

#### Invoices & Lines

| **Stripe**                        | **Fincome**                 |
| --------------------------------- | --------------------------- |
| id                                | original\_id (invoice)      |
| customer                          | customer\_id                |
| status                            | status                      |
| number                            | invoice\_number             |
| status\_transitions.finalized\_at | date                        |
| lines\[].id                       | original\_id (line)         |
| subscription                      | subscription\_id            |
| quantity                          | quantity                    |
| tax\_amount                       | tax\_amount                 |
| discount\_amount                  | discount\_amount            |
| period.start / period.end         | period\_start / period\_end |
| currency                          | currency\_code              |

#### Credit Notes

| **Stripe**                  | **Fincome**                     |
| --------------------------- | ------------------------------- |
| id                          | original\_id                    |
| invoice                     | invoice\_id                     |
| status                      | status                          |
| created                     | date                            |
| lines\[].id                 | original\_id (credit note line) |
| invoice\_line\_item         | invoice\_line\_item\_id         |
| amount                      | amount(\_main)                  |
| discount\_amount            | discount\_amount                |
| temporary\_discount\_amount | temporary\_discount\_amount     |
| currency                    | currency\_code                  |
| description                 | description                     |

***

### Next steps

* View your KPIs in the MRR, Churn, and Cohorts views
* Add other billing sources (Stripe, Chargebee, etc.)
* Enrich your customer data (segmentation, company size...)
* Schedule a session with your Customer Success to go further