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

# Mapping d'intégration Chargebee

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

[Suivez ce guide](https://help.fincome.co/fr/article/connecter-mon-compte-chargebee-12i68pq/) pour établir la connexion avec l'API Chargebee.
---
# Données synchronisées

| **Entité** | **Champs clés synchronisés** |
| ---- |
| Clients | id, nom, email, pays, code_postal |
| Produits (Products) | id, nom |
| Prix (Prices) | id, nom, durée, période, type, montant, devise, type_d’item |
| Abonnements (Subscriptions) | id, client_id, statut, dates_d’essai, début_abonnement, annulation, fin_d’engagement |
| Factures (Invoices) | id, statut, client, date |
| Lignes de facture (Invoice Lines) | prix_lié, description, montants_HT, remises (temp/perm), taxes, quantité, période, devise |
| Avoirs (Credit Notes) | id, statut, facture_d’origine |
| Lignes d’avoir (Credit Note Lines) | même structure que la facture (avec inversion des montants) |
---
# Fonctionnement détaillé de l'intégration

* Mapping champ à champ : chaque entité Chargebee est traduite finement selon le mapping fourni par l’API
* Multi-lignes d’abonnement : Fincome analyse les subscription.subscription_items unitairement
* Annulations interprétées : cancelled_at, cancel_schedule_created_at sont pris en compte
* MRR reconstitué : à partir des prix associés à chaque item_price actif, ajusté selon la période
* Remises différenciées : temporaires et permanentes traitées séparément, par ligne
* Conversion devise : basée sur currency_code + created_at (ou date) selon le type d'objet
---
# À savoir

* Synchronisation initiale : dépend de l’historique, peut prendre quelques heures
* Mise à jour automatique : toutes les nuits + mise à jour via webhook
* Champs personnalisés : disponibles via metadata dans les objets customer et subscription
* Remontée des lignes annulées : via deleted_at
* Avoirs non “voided” uniquement : les avoirs annulés ne sont pas importés
* Suppression manuelle dans Chargebee : non propagée
---
# Vue d'ensemble de l'intégration

| **Élément** | **Détail** |
| ---- |
| Méthode d’intégration | OAuth 2.0 (connexion directe via App Store) |
| Entités prises en charge | Clients, Produits, Prix, Abonnements, Factures, Avoirs |
| Fréquence de synchronisation | Quotidienne + Webhooks temps réel |
| Portée de l’import initial | Toutes les données disponibles via API |
| Méthode de synchronisation | API REST Chargebee avec pagination |
| Suppression de données Chargebee | Gérée via deleted ou IdPathOrResourceDeleted |
---
# Paramètres de données

| **Réglage ou champ** | **Fonctionnement dans Fincome** |
| ---- |
| subscription_items | Chaque ligne est suivie individuellement |
| Détection des essais | Champs trial_start et trial_end |
| Dates d’abonnement | started_at ou start_date |
| Fin d’engagement contractuel | Reconstituée via méthode dédiée (GetContractualCommitmentEndDate) |
| Remises ligne à ligne | temporary_discount_amount vs discount_amount |
| Conversion de devise | Via currency_code + created_at ou invoice.date |
| Abonnements supprimés | deleted_at est valorisé si l’abonnement a disparu |
---
# Mapping technique (Chargebee → Fincome)

### Clients

| **Champ Chargebee** | **Champ Fincome** |
| ---- |
| 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 |

### Produits & Prix

| **Champ Chargebee** | **Champ Fincome** |
| ---- |
| item.id | original_id (produit) |
| item.name | name (produit) |
| item_family_id | chargebee_item_family (axe) |
| item_price.id | original_id (prix) |
| item_price.name | name (prix) |
| 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 (axe) |

### Abonnements

| **Champ Chargebee** | **Champ Fincome** |
| ---- |
| 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 |
| calculé | monthly_value, monthly_value_main |
| subscription.metadata | custom_axis_field |

### Factures & Lignes

| **Champ Chargebee** | **Champ Fincome** |
| ---- |
| invoice.id | original_id |
| invoice.date | date |
| invoice.status | status |
| invoice.customer_id | customer_id |
| invoice.line_items\[].id | original_id (ligne) |
| 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 |

### Avoirs

| **Champ Chargebee** | **Champ Fincome** |
| ---- |
| credit_note.id | original_id |
| credit_note.line_items | lignes d’avoir |
| credit_note.status != voided | filtre d’import |
| 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 |

###### Avoirs : comptabilisation selon le motif

Le motif (`reason_code`) de l'avoir Chargebee détermine la manière dont il est comptabilisé sur Fincome :

| **Motif de l'avoir** | **Traitement dans Fincome** |
| ---- |
| `subscription_change` ou `subscription_cancellation` | Ligne de facture négative (fait généralement référence à de la proration) |
| Tout autre motif, ou absence de motif | Réel avoir (credit note) |

Cette distinction permet de refléter correctement les ajustements de proration (changement ou résiliation d'abonnement) comme des corrections de facturation, tout en conservant les véritables avoirs en tant que tels dans le calcul du MRR et des KPIs.

---

# Prochaines étapes

* Consultez vos KPIs dans les vues MRR, Churn, et Cohortes
* Ajoutez d’autres sources de facturation (Stripe, Chargebee, etc.)
* Enrichissez vos données clients (segmentation, taille d’entreprise...)
* Planifiez une session avec votre Customer Success pour aller plus loin