# Chargebee integration mapping

### Connecting to Chargebee

[Follow this guide ](https://help.fincome.co/en/guide/sources/connect-my-chargebee-account)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