Stripe integration mapping
Connecting to Stripe
Follow this guide 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 |
address.country / shipping.address.country | country |
address.postal_code / shipping.address.postal_code | zip_code |
Products & Prices
Stripe | Fincome |
|---|---|
original_id (product) | |
name (product) | |
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 |
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
Updated on: 03/07/2026
Thank you!