# Chargebee integration mapping ### Connecting to Chargebee [Follow this guide ](/help-center/en/guide/sources/connect-my-chargebee-account.md)to establish the connection with the Chargebee API. ### Synchronized data | **Entity** | **Synchronized key fields** | | ----------------- | -------------------------------------------------------------------------------------------------------- | | Customers | id, name, email, country, postal\_code | | Products | id, name | | Prices (Prices) | id, name, duration, period, type, amount, currency, item\_type | | Subscriptions | id, customer\_id, status, trial\_dates, subscription\_start, cancellation, commitment\_end | | Invoices | id, status, customer, date | | Invoice Lines | linked\_price, description, amounts\_excl\_tax, discounts (temp/perm), taxes, quantity, period, currency | | Credit Notes | id, status, original\_invoice | | Credit Note Lines | same structure as the invoice (with amounts inverted) | *** ### Detailed operation of the integration * Field-to-field mapping: each Chargebee entity is finely translated according to the mapping provided by the API * Multi-line subscriptions: Fincome analyzes subscription.subscription\_items individually * Cancellations interpreted: cancelled\_at, cancel\_schedule\_created\_at are taken into account * Reconstructed MRR: from the prices associated with each active item\_price, adjusted according to the period * Differentiated discounts: temporary and permanent handled separately, per line * Currency conversion: based on currency\_code + created\_at (or date) depending on the object type *** ### Note * Initial synchronization: depends on history, may take a few hours * Automatic update: every night + update via webhook * Custom fields: available via metadata in customer and subscription objects * Reporting of deleted lines: via deleted\_at * Only non-voided credit notes: voided credit notes are not imported * Manual deletion in Chargebee: not propagated *** ### Integration overview | **Item** | **Detail** | | -------------------------- | ------------------------------------------------------------------ | | Integration method | OAuth 2.0 (direct connection via App Store) | | Supported entities | Customers, Products, Prices, Subscriptions, Invoices, Credit Notes | | Sync frequency | Daily + real-time Webhooks | | Scope of initial import | All data available via API | | Synchronization method | Chargebee REST API with pagination | | Deletion of Chargebee data | Managed via deleted or IdPathOrResourceDeleted | *** ### Data settings | **Setting or field** | **Operation in Fincome** | | ----------------------------- | -------------------------------------------------------------------- | | subscription\_items | Each line is tracked individually | | Trial detection | Fields trial\_start and trial\_end | | Subscription dates | started\_at or start\_date | | End of contractual commitment | Reconstructed via dedicated method (GetContractualCommitmentEndDate) | | Line-by-line discounts | temporary\_discount\_amount vs discount\_amount | | Currency conversion | Via currency\_code + created\_at or invoice.date | | Deleted subscriptions | deleted\_at is set if the subscription disappeared | *** ### Technical mapping (Chargebee → Fincome) #### Customers | **Chargebee field** | **Fincome field** | | --------------------------------- | ------------------- | | customer.id | original\_id | | customer.relationship.root\_id | root\_parent\_id | | customer.email | email | | customer.billing\_address.country | country | | customer.billing\_address.zip | zip\_code | | customer.metadata | custom\_axis\_field | #### Products & Prices | **Chargebee field** | **Fincome field** | | -------------------------- | ------------------------------ | | item.id | original\_id (product) | | item.name | name (product) | | item\_family\_id | chargebee\_item\_family (axis) | | item\_price.id | original\_id (price) | | item\_price.name | name (price) | | item\_price.period\_unit | period\_unit | | item\_price.period | period\_length | | item\_price.amount | amount | | item\_price.currency\_code | currency\_code | | item\_price.item\_type | chargebee\_item\_type (axis) | #### Subscriptions | **Chargebee field** | **Fincome field** | | ---------------------------------------------------------- | ------------------------------------ | | subscription.id | original\_id | | subscription.status | status | | subscription.customer\_id | customer\_id | | subscription.subscription\_items\[].item\_price\_id | price\_id | | subscription.started\_at / start\_date | subscription\_start\_date | | subscription.trial\_start | trial\_start | | subscription.trial\_end | trial\_end | | subscription.cancel\_schedule\_created\_at / cancelled\_at | canceled\_at | | subscription.cancelled\_at | effective\_cancellation\_date | | subscription.created\_at | deal\_closed\_date | | calculated | monthly\_value, monthly\_value\_main | | subscription.metadata | custom\_axis\_field | #### Invoices & Lines | **Chargebee field** | **Fincome field** | | ---------------------------- | --------------------------------------- | | invoice.id | original\_id | | invoice.date | date | | invoice.status | status | | invoice.customer\_id | customer\_id | | invoice.line\_items\[].id | original\_id (line) | | item\_price\_id | price\_id | | subscription\_id | subscription\_id | | quantity | quantity | | amount\_after\_discount | amount\_excluding\_tax\_after\_discount | | tax\_amount | tax\_amount | | line\_item\_discounts (perm) | discount\_amount | | line\_item\_discounts (temp) | temporary\_discount\_amount | | description | description | | date\_from, date\_to | period\_start, period\_end | | invoice.currency\_code | currency\_code | #### Credit Notes | **Chargebee field** | **Fincome field** | | --------------------------------- | --------------------------------------- | | credit\_note.id | original\_id | | credit\_note.line\_items | credit note lines | | credit\_note.status != voided | import filter | | amount | amount\_excluding\_tax\_after\_discount | | discount\_amount | discount\_amount | | temporary\_discount\_amount | temporary\_discount\_amount | | description, date\_from, date\_to | description, period\_start, period\_end | *** ### 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/chargebee-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.