Chargebee integration guide
Welcome to the Chargebee integration guide with Fincome. This document guides you step by step to connect your Chargebee billing data to Fincome.
Prerequisites
Before starting, make sure that:
You are the Chargebee account administrator
You have an OAuth connection enabled (via the Chargebee App Store or the API settings)
Your Fincome account is active
You have enabled access to the entities: Customers, Products, Prices, Subscriptions, Invoices and Credit Notes
Introduction to the integration
The Chargebee integration enables automatic synchronization of the following entities into Fincome:
Customers
Products & Prices
Subscriptions & subscription lines
Invoices & invoice lines
Credit notes
This data is normalized in Fincome to produce:
MRR (monthly, net, expansion, contraction, churn)
Subscription cohorts
Revenue recognition
Discount analysis (temporary vs permanent)
Multi-currency management
Customer lifetime and churn analysis
Integration steps
1. Connect to Chargebee from Fincome
Log in to your Fincome account.
Go to the Data tab.
Click Connect a new billing system:
Select Chargebee.
On another page, log in to your Chargebee account.
Go to Settings > Configure Chargebee > API Key > Add a read-only key and select "All".
Copy this key and paste it on your Fincome page.
On your Chargebee page copy what is between "https://" and ".chargebee.com" and paste it on the Fincome page.
Confirm.
Once the connection is established, the initial synchronization starts automatically.
2. Data synchronized
Customers
ID, name, email, country, postal code, parent (customer hierarchy)
Products & Prices
Product: ID, name, family
Price: ID, name, duration, period, type, amount, currency, item type
Subscriptions
ID, linked customer, status, trial dates, subscription start, cancellation, end of commitment
Subscription lines (item_price) analyzed one by one
Monthly amounts calculated, in original currency and base currency
Invoices & Lines
Invoice: ID, status, customer, date
Line: linked price, description, amounts before tax, discounts (temp/perm), taxes, quantity, period, currency
Credit notes
Credit note: ID, status, original invoice
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-subscription lines: Fincome analyzes subscription.subscription_items individually
Cancellations interpreted: cancelled_at, cancel_schedule_created_at are taken into account
Contractual commitments: reconstructed via GetContractualCommitmentEndDate()
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
Deletion or inactive resource: handled with IdPathOrResourceDeleted(...)
To know
Initial synchronization: depends on history, may take a few hours
Automatic update: every night + update via webhook
Custom fields: available via metadata in the customer and subscription objects
Bringing back canceled lines: via deleted_at
Only credit notes not “voided”: 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
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
Managed via deleted or IdPathOrResourceDeleted
Data settings
Setting or field
How it works 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 populated 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
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
computed
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
Need help?
Our support team is available via the in-app chat or by email: [email protected]
Next steps
Check 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
Last updated