Mapping d'intégration Chargebee

Connexion à Chargebee

Suivez ce guide 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

---

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