> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.fincome.co/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Chargebee integration mapping

![](https://storage.crisp.chat/users/helpdesk/website/-/6/2/0/e/620ea71851239000/chargebee_1fhfm8r.webp =100x100)
# Connecting to Chargebee

[Follow this guide](https://help.fincome.co/en/article/connect-my-chargebee-account-6tlias/) to establish the connection with the Chargebee API.
---
# Synchronized data

| **Entity** | **Key synchronized fields** |
| ---- |
| Customers | id, name, email, country, zip_code |
| Products | id, name |
| 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) |
---
# How the integration works in detail

* Field-by-field mapping: each Chargebee entity is translated precisely 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
* MRR reconstituted: 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
---
# Good to know

* Initial synchronization: depends on the history, can take a few hours
* Automatic update: every night + update via webhook
* Custom fields: available via metadata in the customer and subscription objects
* Retrieval of deleted lines: via deleted_at
* Non-"voided" credit notes only: voided credit notes are not imported
* Manual deletion in Chargebee: not propagated
---
# Integration overview

| **Element** | **Detail** |
| ---- |
| Integration method | OAuth 2.0 (direct connection via App Store) |
| Supported entities | Customers, Products, Prices, Subscriptions, Invoices, Credit notes |
| Synchronization frequency | Daily + real-time Webhooks |
| Scope of the initial import | All data available via API |
| Synchronization method | Chargebee REST API with pagination |
| Chargebee data deletion | Handled via deleted or IdPathOrResourceDeleted |
---
# Data settings

| **Setting or field** | **How it works in Fincome** |
| ---- |
| subscription_items | Each line is tracked individually |
| Trial detection | trial_start and trial_end fields |
| Subscription dates | started_at or start_date |
| Contractual commitment end | Reconstituted via a 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 has 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 (dimension) |
| 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 (dimension) |

### 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 |

###### Credit notes: accounting according to the reason

The reason (`reason_code`) of the Chargebee credit note determines how it is accounted for in Fincome:

| **Credit note reason** | **Treatment in Fincome** |
| ---- |
| `subscription_change` or `subscription_cancellation` | Negative invoice line (generally refers to proration) |
| Any other reason, or no reason | Actual credit note |

This distinction correctly reflects proration adjustments (subscription change or termination) as billing corrections, while keeping true credit notes as such in the calculation of MRR and KPIs.

---

# 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