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

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

Mis à jour le : 25/06/2026

Cet article a-t-il répondu à vos questions ?

Merci !