Stripe integration mapping

Connecting to Stripe

Follow this guide 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 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 mapping of objects Each Stripe entity (customer, product, subscription, invoice...) is translated into Fincome through 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 tracking of subscriptions 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 dates.

• 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 analysis of discounts 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 change made in Fincome remains prioritized over synchronized data.

---

Note

• 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 overwrite 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 tokens expiration The OAuth connection is automatically refreshed if needed. No intervention is required from you.

---

Overview of the integration

Item	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
Deletion of Stripe data	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	Tracking by line (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

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