Chargebee integration mapping
Connecting to Chargebee
Follow this guide to establish the connection with the Chargebee API.
Synchronized data
Entity
Key fields synchronized
Customers
id, name, email, country, postal_code
Products
id, name
Prices
id, name, duration, period, type, amount, currency, item_type
Subscriptions
id, customer_id, status, trial_dates, subscription_start, cancellation, end_of_commitment
Invoices
id, status, customer, date
Invoice Lines
linked_price, description, amounts_excl_tax, discounts (temp/perm), taxes, quantity, period, currency
Credit Notes
id, status, originating_invoice
Credit Note Lines
same structure as invoice (with amounts reversed)
Detailed operation of the integration
Field-to-field mapping: each Chargebee entity is precisely 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
Reconstructed MRR: from the prices associated with each active item_price, adjusted according to the period
Differentiated discounts: temporary and permanent discounts handled separately, per line
Currency conversion: based on currency_code + created_at (or date) depending on the object type
Note
Initial synchronization: depends on history, may take several hours
Automatic update: every night + updates via webhook
Custom fields: available via metadata in the customer and subscription objects
Reporting of deleted lines: via deleted_at
Only non-voided credit notes: canceled 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 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
Operation 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 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
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
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