# Stripe integration mapping ### Connect to Stripe [Follow this guide](/help-center/en/guide/sources/connect-my-stripe-account.md) 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://fincome.gitbook.io/help-center/en/resources/integration-mapping-and-api/stripe-integration-mapping.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.