> ## 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).

# Stripe integration mapping

![](https://storage.crisp.chat/users/helpdesk/website/-/6/2/0/e/620ea71851239000/stripe_1squotp.png =100x100)
# Connecting to Stripe

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

| **Stripe entity** | **Key synchronized 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 |
---
# How the integration works in detail

The Stripe integration with Fincome is designed to guarantee a faithful, granular reading of your billing data. Here are the main mechanisms at work:

* **Structured object mapping**
  Each Stripe entity (customer, product, subscription, invoice...) is translated into Fincome via a field-by-field mapping, according to the rules defined in our integration engine.

* **Trial period detection**
  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 `canceled`, `unpaid`, `incomplete_expired` statuses are correctly interpreted. The `cancel_at`, `canceled_at`, and `pause_collection` fields allow a faithful rendering of commitment ends.

* **MRR calculation**
  The 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 at the creation date.

* **Complete discount analysis**
  Fincome distinguishes and values:
* **temporary** discounts (e.g.: coupons with a limited duration)
* **permanent** discounts (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 issue date of each document (invoice, credit note...).

* **Incremental, prioritized synchronization**
  Stripe updates are automatically detected via Webhooks (e.g.: `invoice.updated`, `customer.subscription.updated`).\
  Any manual change made in Fincome takes precedence over the synchronized data.
---
# Good to know

* **Duration of the first synchronization**
  It can take several hours depending on the volume of subscribers, invoices, or history to import.

* **Daily synchronization**
  Fincome synchronizes Stripe automatically **every night**, including new data and updates.

* **Manual override**
  Any change made manually in Fincome (e.g.: reassigning a subscription) **is never overwritten** by the Stripe synchronization.

* **Stripe rate limit**
  The API limitations imposed by Stripe are handled automatically. Fincome pauses and resumes the synchronization without manual action.

* **OAuth token expiration**
  The OAuth connection is automatically refreshed if needed. No intervention is required on your part.
---
# Integration overview

| **Element** | **Detail** |
| ---- |
| Integration method | OAuth 2.0 (direct connection from Fincome) |
| Supported entities | Customers, Products, Prices, Subscriptions, Invoices, Credit notes |
| Synchronization frequency | Daily + Webhooks |
| Initial import | Full Stripe history |
| Synchronization method | REST API with starting_after pagination |
| Stripe data deletion | Not supported (not propagated to Fincome) |
---
# Data settings

| **Setting** | **How it works** |
| ---- |
| Trial detection | trial_start and trial_end |
| MRR calculation | Periodicity + amount + currency at the date |
| Commitment end | cancel_at or canceled_at |
| Cancellation | Status + pause_collection, cancel_at |
| Subscriptions | Tracked per line (items.data) |
| Discounts | Coupons: temporary or permanent |
| Currency conversion | currency + invoice date |
| Re-synchronization | 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

* Check your KPIs in the MRR, Churn, and Cohort 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