Stripe integration guide

Welcome to the Stripe integration guide with Fincome. This document accompanies you step by step to connect your Stripe billing data.

Prerequisites

Before starting, make sure that:

  • You are an administrator of your Stripe account.

  • Your Stripe API key (Public key and Secret key) is at hand.

  • Your Fincome environment allows OAuth redirects or manual entry of API keys (HTTPS required).

Introduction to the integration

The Stripe ↔ Fincome integration automatically syncs the following entities from Stripe into Fincome:

  • Customers

  • Products & Prices

  • Subscriptions

  • Invoices & Invoice Line Items

  • Credit Notes (CreditNotes & CreditNoteLineItems)

  • Billing events (webhooks invoice.updated, etc.)

These data are transformed in Fincome to produce key metrics such as:

  • the MRR and its variations (new, expansions, contractions, churn)

  • the customer churn and financial

  • the subscription cohorts

  • thediscount analysis (temporary and permanent)

  • the revenue recognition monthly

  • the multi-currency breakdown (automatic conversion)

Integration steps

1. Connect to Stripe from Fincome

  1. Log in to your Fincome account.

  2. Go to the Data tab.

  3. Click on Connect a new billing system:

  1. Select Stripe.

  2. An OAuth window opens: sign in to your Stripe account and authorize Fincome access.

  3. Once the connection is established, the initial synchronization starts automatically.

2. Synchronized data

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 invoice 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 at work:

  • Structured object mapping Each Stripe entity (customer, product, subscription, invoice...) is translated into Fincome via 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 upsells or downgrades, reactivations, pauses, etc.

  • Cancellations & suspensions The statuses canceled, unpaid, incomplete_expired are correctly interpreted. The fields cancel_at, canceled_at and pause_collection allow an accurate representation of contract end 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 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 prioritized 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 modification made in Fincome (e.g.: reassignment of a subscription) is never overwritten by the Stripe synchronization.

  • Stripe Webhooks Fincome listens to events invoice.updated, customer.subscription.updated, credit_note.updated, etc. for real-time updating.

  • 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 on your part.

Integration overview

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

Line-level tracking (items.data)

Discounts

Coupons: temporary or permanent

Currency conversion

currency + document date

Resynchronization

Automatic (manual changes take priority)

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 (interpreted)

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

computed

monthly_value(_main)

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

computed

amount_excl_tax_after_discount

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

Need help?

Our support team is available via the in-app chat or by email: [email protected]

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

PreviousHyperline integration guideNextChargebee integration guide

Last updated