This article is also available in:

Chargebee integration mapping

Connecting to Chargebee

Follow this guide 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

Updated on: 03/07/2026

Was this article helpful?

Thank you!